Model Context Protocol (MCP)

Give any AI tool persistent memory with the Honcho MCP server

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

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

Windows

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 \
  --url "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

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

Windows

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

---

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