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"
      }
    }
  }
}

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

Using the Tools

Verify It Works

Troubleshooting

​Client Setup

​Claude Desktop

​Claude Code

​Codex

​Cursor

​Windsurf

​VS Code (Copilot Chat)

​Cline

​Zed

​Goose

​Optional Configuration

​Using the Tools

​Verify It Works

​Troubleshooting

Client Setup

Claude Desktop

Claude Code

Codex

Cursor

Windsurf

VS Code (Copilot Chat)

Cline

Zed

Goose

Optional Configuration

Using the Tools

Verify It Works

Troubleshooting