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. Server URL: https://mcp.honcho.dev

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

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}",
        "--header",
        "X-Honcho-User-Name:${USER_NAME}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer hch-your-key-here",
        "USER_NAME": "YourName"
      }
    }
  }
}

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 \
  --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 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",
  "--header",
  "X-Honcho-User-Name:YourName"
]

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

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

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",
        "X-Honcho-User-Name": "YourName"
      }
    }
  }
}

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",
          "X-Honcho-User-Name": "YourName"
        }
      }
    }
  }
}

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

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

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

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

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.

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

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

Optional Configuration

Available Tools

Verify It Works

Troubleshooting

​Client Setup

​Claude Desktop

​Claude Code

​Codex

​Cursor

​Windsurf

​VS Code (Copilot Chat)

​Cline

​Zed

​Goose

​Optional Configuration

​Available Tools

​Verify It Works

​Troubleshooting

Client Setup

Claude Desktop

Claude Code

Codex

Cursor

Windsurf

VS Code (Copilot Chat)

Cline

Zed

Goose

Optional Configuration

Available Tools

Verify It Works

Troubleshooting