# Connect AI Clients (MCP)

Let external AI clients send messages to your Hallway agent through the browser sidebar. This uses the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) standard, so it works with any compatible client.

{% hint style="info" %}
Claude Desktop uses a one-click MCPB installer. Other clients use a one-line terminal install that requires [Node.js](https://nodejs.org/) (v18+) on your machine.
{% endhint %}

## Setup

Pick your AI client:

{% tabs %}
{% tab title="Claude Desktop" %}
{% stepper %}
{% step %}

#### Download and install the Hallway MCPB

<a href="https://hallway-public.nyc3.cdn.digitaloceanspaces.com/2026/plugin/hallway-0.5.1.mcpb" class="button primary">Download Claude installer</a>

Open the downloaded `.mcpb` file in Claude Desktop and approve the installation.
{% endstep %}

{% step %}

#### Restart Claude Desktop and Chrome

Restart Claude Desktop, then restart Chrome or reload the Hallway extension at `chrome://extensions`.
{% endstep %}

{% step %}

#### Open the Hallway sidepanel

The sidepanel must be open in Chrome for messages to go through. Click the Hallway icon in your browser toolbar to open it.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Cursor" %}
{% stepper %}
{% step %}

#### Register the native bridge

Run this in your terminal. It registers the bridge and writes the Cursor MCP config when Cursor is installed.

```bash
npx @hallway-ai/bridge install
```

{% endstep %}

{% step %}

#### Restart Chrome and Cursor

Restart Chrome, or reload the extension at `chrome://extensions`, then restart Cursor.
{% endstep %}

{% step %}

#### Open the Hallway sidepanel

The sidepanel must be open in Chrome for messages to go through.
{% endstep %}
{% endstepper %}

If the installer could not write `~/.cursor/mcp.json`, add it manually:

```json
{
  "mcpServers": {
    "hallway": {
      "command": "npx",
      "args": ["@hallway-ai/bridge", "mcp"]
    }
  }
}
```

{% endtab %}

{% tab title="Codex" %}
{% stepper %}
{% step %}

#### Register the native bridge

Run this in your terminal:

```bash
npx @hallway-ai/bridge install
```

{% endstep %}

{% step %}

#### Add the Codex MCP server

Run this in your terminal:

```bash
codex mcp add hallway -- npx @hallway-ai/bridge mcp
```

{% endstep %}

{% step %}

#### Restart Chrome

Restart Chrome, or reload the extension at `chrome://extensions`, then open the Hallway sidepanel.
{% endstep %}
{% endstepper %}

Or add this manually to `~/.codex/config.toml`:

```toml
[mcp_servers.hallway]
command = "npx"
args = ["@hallway-ai/bridge", "mcp"]
```

Verify with `codex mcp list`.
{% endtab %}

{% tab title="Windsurf" %}
{% stepper %}
{% step %}

#### Register the native bridge

Run this in your terminal. It registers the bridge and writes the Windsurf MCP config when Windsurf is installed.

```bash
npx @hallway-ai/bridge install
```

{% endstep %}

{% step %}

#### Restart Chrome and Windsurf

Restart Chrome, or reload the extension at `chrome://extensions`, then restart Windsurf.
{% endstep %}

{% step %}

#### Open the Hallway sidepanel

The sidepanel must be open in Chrome for messages to go through.
{% endstep %}
{% endstepper %}

If the installer could not write your Windsurf MCP config, add it manually:

* **macOS/Linux:** `~/.codeium/windsurf/mcp_config.json`
* **Windows:** `%USERPROFILE%\.codeium\windsurf\mcp_config.json`

```json
{
  "mcpServers": {
    "hallway": {
      "command": "npx",
      "args": ["@hallway-ai/bridge", "mcp"]
    }
  }
}
```

{% endtab %}
{% endtabs %}

## Available Tools

Once connected, your AI client will have access to:

| Tool           | Description                                                              |
| -------------- | ------------------------------------------------------------------------ |
| `send_message` | Send a chat message to the Hallway agent, same as typing in the sidebar. |

The tool sends your message through the Chrome sidebar, and the agent's full response is returned back to your AI client.

## How It Works

```
AI Client (Cursor/Claude) → MCP Server → WebSocket → Native Bridge → Chrome Extension → Sidebar → Agent
```

The bridge uses Chrome's [Native Messaging](https://developer.chrome.com/docs/extensions/develop/concepts/native-messaging) API to communicate between external processes and the extension. The MCP server translates between the MCP protocol and the bridge.

## Troubleshooting

<details>

<summary>"bridge not connected" error</summary>

The bridge process isn't running. Make sure:

1. You ran the Hallway Bridge Installer or the terminal fallback
2. You restarted Chrome after installing
3. The Hallway extension is enabled in `chrome://extensions`

You can check the installation status with:

```bash
npx @hallway-ai/bridge status
```

</details>

<details>

<summary>"sidebar not open" error</summary>

The Hallway sidepanel must be open in Chrome for messages to be delivered. Click the Hallway icon in your browser toolbar to open it.

</details>

<details>

<summary>Messages send but no response comes back</summary>

The agent may still be processing. The tool waits up to 3 minutes for a response. If the agent is doing a long browsing task, the response may come back as a timeout — the message was still delivered.

</details>

<details>

<summary>Checking bridge status</summary>

Run this to see if the native bridge is properly installed:

```bash
npx @hallway-ai/bridge status
```

This shows which browsers have the bridge registered and whether the launcher is in place.

</details>

## Uninstall

To remove the native bridge:

```bash
npx @hallway-ai/bridge uninstall
```

Then remove the `hallway` entry from your MCP client config.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hallway.gitbook.io/embed/plugin/connect-ai-clients.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.