Model Context Protocol (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. Hosted URL: https://mcp.honcho.dev

You’ll need an API key from app.honcho.dev to use the hosted MCP server.

Self-hosting Honcho, or want the client to spawn the server itself? Skip mcp.honcho.dev and run the MCP server locally over stdio, Streamable HTTP, or Docker.

Client Setup

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

Claude Desktop

macOS
Windows

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

Edit %APPDATA%\Claude\claude_desktop_config.json:

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

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

For best results, create a project and paste these instructions into the “Project Instructions” field so Claude knows how to use the memory tools.

Claude Code

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 for a deeper integration with persistent memory, git awareness, and agent skills:

/plugin marketplace add plastic-labs/claude-honcho

Codex

Add to ~/.codex/config.toml:

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

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

Cursor

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

{
  "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:

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

Windsurf uses serverUrl instead of url.

VS Code (Copilot Chat)

Add to your workspace .vscode/mcp.json:

{
  "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)”):

{
  "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:

macOS
Windows

~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

{
  "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:

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

Zed uses context_servers instead of mcpServers. Native HTTP support requires Zed v0.214.5 or later.

Goose

Goose 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):

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

To teach Goose the recommended memory flow, save the instructions 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.

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, clone plastic-labs/honcho, then:

cd mcp && bun install

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.

honcho start starts API, deriver, Postgres, and Redis — not MCP. Use stdio below, or run the HTTP host next to that stack.

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:

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

{
  "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.

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:

claude mcp add honcho \
  --transport http \
  "http://127.0.0.1:3000" \
  --header "Authorization: Bearer hch-your-key-here"

Or with mcp-remote:

{
  "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:

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:

curl http://127.0.0.1:3000/health

Point clients at http://127.0.0.1:3000 the same way as the HTTP section above. See the local environment guide 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.

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. It should start with `hch-`. Local HTTP: send `Authorization: Bearer` on every request, including after initialize.
`npx` / `bun` not found	Install Node.js (for `npx` / `mcp-remote`) or Bun (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 or open an issue on GitHub.

Overview

Integrations

Tutorials

Community Integrations

Migrations

Model Context Protocol (MCP)

Client Setup

Claude Desktop

Claude Code

Codex

Cursor

Windsurf

VS Code (Copilot Chat)

Cline

Zed

Goose

Run locally

Stdio

HTTP

HTTP in Docker

Workspace

Using the Tools

Verify It Works

Troubleshooting

​Client Setup

​Claude Desktop

​Claude Code

​Codex

​Cursor

​Windsurf

​VS Code (Copilot Chat)

​Cline

​Zed

​Goose

​Run locally

​Stdio

​HTTP

​HTTP in Docker

​Workspace

​Using the Tools

​Verify It Works

​Troubleshooting

Client Setup

Claude Desktop

Claude Code

Codex

Cursor

Windsurf

VS Code (Copilot Chat)

Cline

Zed

Goose

Run locally

Stdio

HTTP

HTTP in Docker

Workspace

Using the Tools

Verify It Works

Troubleshooting