---
title: "Model Context Protocol (MCP)"
icon: 'star-of-life'
description: "Give any AI tool persistent memory with the Honcho MCP server"
sidebarTitle: 'MCP'
---

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.

**Server 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>

## 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
{
  "mcpServers": {
    "honcho": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.honcho.dev",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--header",
        "X-Honcho-User-Name:${USER_NAME}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer hch-your-key-here",
        "USER_NAME": "YourName"
      }
    }
  }
}
```

<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
claude mcp add honcho \
  --transport http \
  --url "https://mcp.honcho.dev" \
  --header "Authorization: Bearer hch-your-key-here" \
  --header "X-Honcho-User-Name: YourName"
```

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

```bash
/plugin marketplace add plastic-labs/claude-honcho
```

### Codex

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

```toml
[mcp_servers.honcho]
command = "npx"
args = [
  "mcp-remote",
  "https://mcp.honcho.dev",
  "--header",
  "Authorization:Bearer hch-your-key-here",
  "--header",
  "X-Honcho-User-Name:YourName"
]
```

<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
{
  "mcpServers": {
    "honcho": {
      "url": "https://mcp.honcho.dev",
      "headers": {
        "Authorization": "Bearer hch-your-key-here",
        "X-Honcho-User-Name": "YourName"
      }
    }
  }
}
```

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
{
  "mcpServers": {
    "honcho": {
      "serverUrl": "https://mcp.honcho.dev",
      "headers": {
        "Authorization": "Bearer hch-your-key-here",
        "X-Honcho-User-Name": "YourName"
      }
    }
  }
}
```

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

### VS Code (Copilot Chat)

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

```json
{
  "servers": {
    "honcho": {
      "type": "http",
      "url": "https://mcp.honcho.dev",
      "headers": {
        "Authorization": "Bearer hch-your-key-here",
        "X-Honcho-User-Name": "YourName"
      }
    }
  }
}
```

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

```json
{
  "mcp": {
    "servers": {
      "honcho": {
        "type": "http",
        "url": "https://mcp.honcho.dev",
        "headers": {
          "Authorization": "Bearer hch-your-key-here",
          "X-Honcho-User-Name": "YourName"
        }
      }
    }
  }
}
```

### 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
{
  "mcpServers": {
    "honcho": {
      "url": "https://mcp.honcho.dev",
      "headers": {
        "Authorization": "Bearer hch-your-key-here",
        "X-Honcho-User-Name": "YourName"
      }
    }
  }
}
```

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

### Zed

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

```json
{
  "context_servers": {
    "honcho": {
      "url": "https://mcp.honcho.dev",
      "headers": {
        "Authorization": "Bearer hch-your-key-here",
        "X-Honcho-User-Name": "YourName"
      }
    }
  }
}
```

<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 headers `Authorization: Bearer hch-your-key-here` and `X-Honcho-User-Name: YourName`.

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

```yaml
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"
      X-Honcho-User-Name: "YourName"
    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>

---

## Optional Configuration

You can customize the assistant name and workspace ID by adding extra headers. Both are optional.

| Header | Default | Description |
|--------|---------|-------------|
| `Authorization` | *required* | `Bearer hch-your-key-here` |
| `X-Honcho-User-Name` | *required* | What the AI should call you |
| `X-Honcho-Assistant-Name` | `"Assistant"` | Name for the AI peer |
| `X-Honcho-Workspace-ID` | `"default"` | Isolate memory per project |

Example with all headers (Claude Desktop format):

```json
{
  "mcpServers": {
    "honcho": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.honcho.dev",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--header",
        "X-Honcho-User-Name:${USER_NAME}",
        "--header",
        "X-Honcho-Assistant-Name:${ASSISTANT_NAME}",
        "--header",
        "X-Honcho-Workspace-ID:${WORKSPACE_ID}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer hch-your-key-here",
        "USER_NAME": "YourName",
        "ASSISTANT_NAME": "Claude",
        "WORKSPACE_ID": "my-project"
      }
    }
  }
}
```

---

## Available Tools

The recommended flow for a standard conversation uses `create_session` + `add_messages_to_session` + `chat`. See the [full instructions](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md) for a complete walkthrough.

**Workspace** — `inspect_workspace`, `list_workspaces`, `search`, `get_metadata`, `set_metadata`

**Peers** — `create_peer`, `list_peers`, `chat`, `get_peer_card`, `set_peer_card`, `get_peer_context`, `get_representation`

**Sessions** — `create_session`, `list_sessions`, `delete_session`, `clone_session`, `add_peers_to_session`, `remove_peers_from_session`, `get_session_peers`, `inspect_session`, `add_messages_to_session`, `get_session_messages`, `get_session_message`, `get_session_context`

**Conclusions** — `list_conclusions`, `query_conclusions`, `create_conclusions`, `delete_conclusion`

**System** — `schedule_dream`, `get_queue_status`

---

## 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 | Check your API key at [app.honcho.dev](https://app.honcho.dev). It should start with `hch-`. |
| `npx` not found | Install Node.js — your AI assistant can help with this. |
| "No personalization insights found" | Normal for new users. Honcho needs a few conversations to build context. |
| Connection timeouts | Check that `https://mcp.honcho.dev` is accessible from your network. |

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).