> ## Documentation Index
> Fetch the complete documentation index at: https://honcho.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol (MCP)

> Give any AI tool persistent memory with the Honcho MCP server

The Honcho MCP server gives any MCP-compatible AI tool persistent memory and personalization. Connect it once and your AI assistant learns who you are, remembers your preferences, and gets better over time — across every conversation.

**Hosted URL:** `https://mcp.honcho.dev`

<Note>
  You'll need an API key from [app.honcho.dev](https://app.honcho.dev) to use the hosted MCP server.
</Note>

<Tip>
  Self-hosting Honcho, or want the client to spawn the server itself? Skip `mcp.honcho.dev` and [run the MCP server locally](#run-locally) over stdio, Streamable HTTP, or Docker.
</Tip>

## Client Setup

Pick your client below and add the config. After adding, **restart the client fully** for changes to take effect.

### Claude Desktop

<Tabs>
  <Tab title="macOS">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
  </Tab>

  <Tab title="Windows">
    Edit `%APPDATA%\Claude\claude_desktop_config.json`:
  </Tab>
</Tabs>

```json theme={null}
{
  "mcpServers": {
    "honcho": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.honcho.dev",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer hch-your-key-here"
      }
    }
  }
}
```

<Tip>
  After saving, fully quit and relaunch Claude Desktop. The Honcho tools should appear in the tool picker.
</Tip>

For best results, create a project and paste these [instructions](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md) into the "Project Instructions" field so Claude knows how to use the memory tools.

### Claude Code

```bash theme={null}
claude mcp add honcho \
  --transport http \
  "https://mcp.honcho.dev" \
  --header "Authorization: Bearer hch-your-key-here"
```

Or if you prefer the [Claude Code Honcho plugin](/docs/v3/guides/integrations/claudecode) for a deeper integration with persistent memory, git awareness, and agent skills:

```bash theme={null}
/plugin marketplace add plastic-labs/claude-honcho
```

### Codex

Add to `~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.honcho]
command = "npx"
args = [
  "mcp-remote",
  "https://mcp.honcho.dev",
  "--header",
  "Authorization:Bearer hch-your-key-here"
]
```

<Note>
  Codex only supports stdio transport, so it uses `mcp-remote` as a bridge. Restart both the Codex CLI and VS Code extension after editing.
</Note>

### Cursor

Cursor supports MCP servers natively via HTTP. Add to your global config at `~/.cursor/mcp.json` or per-project at `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "honcho": {
      "url": "https://mcp.honcho.dev",
      "headers": {
        "Authorization": "Bearer hch-your-key-here"
      }
    }
  }
}
```

Alternatively, go to **Cursor Settings → MCP** and add a new HTTP server with the URL and headers above.

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "honcho": {
      "serverUrl": "https://mcp.honcho.dev",
      "headers": {
        "Authorization": "Bearer hch-your-key-here"
      }
    }
  }
}
```

<Note>
  Windsurf uses `serverUrl` instead of `url`.
</Note>

### VS Code (Copilot Chat)

Add to your workspace `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "honcho": {
      "type": "http",
      "url": "https://mcp.honcho.dev",
      "headers": {
        "Authorization": "Bearer hch-your-key-here"
      }
    }
  }
}
```

Or add to your User Settings JSON (`Cmd+Shift+P` → "Preferences: Open User Settings (JSON)"):

```json theme={null}
{
  "mcp": {
    "servers": {
      "honcho": {
        "type": "http",
        "url": "https://mcp.honcho.dev",
        "headers": {
          "Authorization": "Bearer hch-your-key-here"
        }
      }
    }
  }
}
```

### Cline

Cline supports remote MCP servers natively. Open Cline's MCP settings at:

<Tabs>
  <Tab title="macOS">
    `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
  </Tab>

  <Tab title="Windows">
    `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
  </Tab>
</Tabs>

```json theme={null}
{
  "mcpServers": {
    "honcho": {
      "url": "https://mcp.honcho.dev",
      "headers": {
        "Authorization": "Bearer hch-your-key-here"
      }
    }
  }
}
```

Or add it via the Cline sidebar: click the MCP Servers icon → **Configure** → **Remote Servers**.

### Zed

Add to `~/.config/zed/settings.json`:

```json theme={null}
{
  "context_servers": {
    "honcho": {
      "url": "https://mcp.honcho.dev",
      "headers": {
        "Authorization": "Bearer hch-your-key-here"
      }
    }
  }
}
```

<Note>
  Zed uses `context_servers` instead of `mcpServers`. Native HTTP support requires Zed v0.214.5 or later.
</Note>

### Goose

[Goose](https://goose-docs.ai/) supports remote MCP servers natively over Streamable HTTP.

The easiest way is to run `goose configure`, choose **Add Extension → Remote Extension (Streamable HTTP)**, and enter the name `honcho`, the URI `https://mcp.honcho.dev`, and the header `Authorization: Bearer hch-your-key-here`.

Or edit your `config.yaml` directly (on Linux, `~/.config/goose/config.yaml`):

```yaml theme={null}
extensions:
  honcho:
    enabled: true
    type: streamable_http
    name: honcho
    description: Honcho persistent memory & personalization
    uri: https://mcp.honcho.dev
    headers:
      Authorization: "Bearer hch-your-key-here"
    timeout: 60
```

<Tip>
  To teach Goose the recommended memory flow, save the [instructions](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md) into a `.goosehints` file in your Goose config directory (or a project root). This is Goose's equivalent of Claude Desktop's "Project Instructions". Not sure of your config path? Run `goose info`.
</Tip>

***

## Run locally

The hosted URL talks to `api.honcho.dev`. If you run Honcho yourself, run the same MCP tools from this repo's `mcp/` package and point them at your instance with `HONCHO_API_URL`.

Install [Bun](https://bun.sh), clone [plastic-labs/honcho](https://github.com/plastic-labs/honcho), then:

```bash theme={null}
cd mcp && bun install
```

<Info>
  The MCP server always requires a key (`HONCHO_API_KEY` for stdio, `Authorization: Bearer` for HTTP) even when Honcho has `AUTH_USE_AUTH=false`. In that case any non-empty value works.
</Info>

<Note>
  [`honcho start`](/docs/v3/contributing/self-hosting#personal-local-stack-cli) starts API, deriver, Postgres, and Redis — not MCP. Use stdio below, or run the HTTP host next to that stack.
</Note>

### Stdio

The client spawns the server as a subprocess. Use this when the client only speaks stdio (Claude Desktop, Codex) or you want one process per client.

`--cwd` must point at the `mcp/` package so Bun loads `bunfig.toml`.

**Claude Code:**

```bash theme={null}
claude mcp add honcho \
  -e HONCHO_API_KEY=hch-your-key-here \
  -e HONCHO_API_URL=http://127.0.0.1:8000 \
  -e HONCHO_WORKSPACE_ID=my-workspace \
  -- bun --cwd /absolute/path/to/honcho/mcp src/stdio.ts
```

**Claude Desktop** (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "honcho": {
      "command": "bun",
      "args": ["--cwd", "/absolute/path/to/honcho/mcp", "src/stdio.ts"],
      "env": {
        "HONCHO_API_KEY": "hch-your-key-here",
        "HONCHO_API_URL": "http://127.0.0.1:8000",
        "HONCHO_WORKSPACE_ID": "my-workspace"
      }
    }
  }
}
```

`HONCHO_API_URL` defaults to `https://api.honcho.dev`. `HONCHO_WORKSPACE_ID` is optional; without it, pass `workspace_id` on each tool call.

### HTTP

A long-lived Streamable HTTP process. Clients use the same shape as `https://mcp.honcho.dev` — native HTTP, or `mcp-remote` if they only speak stdio.

```bash theme={null}
cd mcp && bun install
HOST=127.0.0.1 HONCHO_API_URL=http://127.0.0.1:8000 bun run http
```

Then point the client at `http://127.0.0.1:3000`:

```bash theme={null}
claude mcp add honcho \
  --transport http \
  "http://127.0.0.1:3000" \
  --header "Authorization: Bearer hch-your-key-here"
```

Or with `mcp-remote`:

```json theme={null}
{
  "mcpServers": {
    "honcho": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:3000",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer hch-your-key-here"
      }
    }
  }
}
```

Bearer auth is required on every request, including established sessions. Optional `X-Honcho-Workspace-ID` fills `workspace_id` when the tool argument is omitted.

`HOST` defaults to `0.0.0.0` (what Docker needs inside the container). For a laptop run, set `HOST=127.0.0.1`. `PORT` defaults to `3000`. `GET /health` is unauthenticated. MCP is served at `/` and `/mcp`.

Sessions live in process memory — run **one** replica. Idle sessions expire after `MCP_SESSION_IDLE_MS` (default 30 minutes); `MCP_SESSION_MAX` (default 128) caps concurrent sessions.

### HTTP in Docker

The HTTP host is what the image runs.

**Standalone**, next to a Honcho API on the host:

```bash theme={null}
docker build -f mcp/Dockerfile -t honcho-mcp mcp
docker run --rm -p 127.0.0.1:3000:3000 \
  -e HONCHO_API_URL=http://host.docker.internal:8000 \
  honcho-mcp
```

On Linux, `host.docker.internal` may need `--add-host=host.docker.internal:host-gateway`.

**Compose:** `docker-compose.yml.example` already includes an `mcp` service beside `api` and `deriver` (`HONCHO_API_URL=http://api:8000`, published at `127.0.0.1:3000`). After `docker compose up -d --build`:

```bash theme={null}
curl http://127.0.0.1:3000/health
```

Point clients at `http://127.0.0.1:3000` the same way as the [HTTP](#http) section above.

See the [local environment guide](/docs/v3/contributing/self-hosting#from-source-docker-compose) for the rest of the stack.

***

## Workspace

Every workspace-scoped tool takes a `workspace_id` argument. You can also set `X-Honcho-Workspace-ID` on the connection; that value fills `workspace_id` when the argument is omitted.

Use `list_workspaces` to discover IDs (each result includes metadata and `created_at`), or `create_workspace` if none fit, then reuse the same ID for subsequent tool calls.

***

## Using the Tools

Once connected, the Honcho MCP server tells your assistant how to use the tools automatically — it ships usage instructions (the recall → respond → record loop, the full tool list, and reasoning levels) on connect, so there's nothing extra to configure.

If you want to read that guidance yourself, it's the [full instructions](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md).

***

## Verify It Works

After setup, try asking your AI assistant:

> "What do you know about me?"

On the first conversation there won't be much — but after a few exchanges, Honcho's background reasoning will start building a representation of you. Ask again after a couple of conversations and you'll see the difference.

***

## Troubleshooting

| Problem | Fix |
| - | - |
| Tools don't show up | Make sure you fully restarted the client after adding the config. |
| Authorization errors | Hosted: check your API key at [app.honcho.dev](https://app.honcho.dev). It should start with `hch-`. Local HTTP: send `Authorization: Bearer` on **every** request, including after initialize. |
| `npx` / `bun` not found | Install [Node.js](https://nodejs.org/) (for `npx` / `mcp-remote`) or [Bun](https://bun.sh) (for local stdio / `bun run http`). |
| Local connection refused | Confirm the MCP process is up (`bun run http`, the compose `mcp` service, or a stdio spawn) and that `HONCHO_API_URL` reaches the API. |
| Local stdio tools missing | Run `bun install` in `mcp/`. `--cwd` must point at that package so Bun loads `bunfig.toml`. |
| "No personalization insights found" | Normal for new users. Honcho needs a few conversations to build context. |
| Connection timeouts | Hosted: check that `https://mcp.honcho.dev` is reachable. Local: check `http://127.0.0.1:3000/health` or the stdio process logs. |

Need help? Join us on [Discord](https://discord.gg/honcho) or open an issue on [GitHub](https://github.com/plastic-labs/honcho/tree/main/mcp).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.