Skip to main content
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

Edit ~/Library/Application Support/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:
~/Library/Application Support/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.

​
Optional Configuration

You can customize the assistant name and workspace ID by adding extra headers. Both are optional.
HeaderDefaultDescription
AuthorizationrequiredBearer hch-your-key-here
X-Honcho-User-NamerequiredWhat 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

ProblemFix
Tools don’t show upMake sure you fully restarted the client after adding the config.
Authorization errorsCheck your API key at app.honcho.dev. It should start with hch-.
npx not foundInstall 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 timeoutsCheck that https://mcp.honcho.dev is accessible from your network.
Need help? Join us on Discord or open an issue on GitHub.