279 lines
7.4 KiB
Plaintext
279 lines
7.4 KiB
Plaintext
---
|
|
title: "Model Context Protocol (MCP)"
|
|
icon: 'star-of-life'
|
|
description: "Give any AI tool persistent memory with the Honcho MCP server"
|
|
sidebarTitle: '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`
|
|
|
|
<Note>
|
|
You'll need an API key from [app.honcho.dev](https://app.honcho.dev) to use the hosted MCP server.
|
|
</Note>
|
|
|
|
## Client Setup
|
|
|
|
Pick your client below and add the config. After adding, **restart the client fully** for changes to take effect.
|
|
|
|
### Claude Desktop
|
|
|
|
<Tabs>
|
|
<Tab title="macOS">
|
|
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
</Tab>
|
|
<Tab title="Windows">
|
|
Edit `%APPDATA%\Claude\claude_desktop_config.json`:
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"honcho": {
|
|
"command": "npx",
|
|
"args": [
|
|
"mcp-remote",
|
|
"https://mcp.honcho.dev",
|
|
"--header",
|
|
"Authorization:${AUTH_HEADER}"
|
|
],
|
|
"env": {
|
|
"AUTH_HEADER": "Bearer hch-your-key-here"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
<Tip>
|
|
After saving, fully quit and relaunch Claude Desktop. The Honcho tools should appear in the tool picker.
|
|
</Tip>
|
|
|
|
For best results, create a project and paste these [instructions](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md) into the "Project Instructions" field so Claude knows how to use the memory tools.
|
|
|
|
### Claude Code
|
|
|
|
```bash
|
|
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](/v3/guides/integrations/claudecode) for a deeper integration with persistent memory, git awareness, and agent skills:
|
|
|
|
```bash
|
|
/plugin marketplace add plastic-labs/claude-honcho
|
|
```
|
|
|
|
### Codex
|
|
|
|
Add to `~/.codex/config.toml`:
|
|
|
|
```toml
|
|
[mcp_servers.honcho]
|
|
command = "npx"
|
|
args = [
|
|
"mcp-remote",
|
|
"https://mcp.honcho.dev",
|
|
"--header",
|
|
"Authorization:Bearer hch-your-key-here"
|
|
]
|
|
```
|
|
|
|
<Note>
|
|
Codex only supports stdio transport, so it uses `mcp-remote` as a bridge. Restart both the Codex CLI and VS Code extension after editing.
|
|
</Note>
|
|
|
|
### Cursor
|
|
|
|
Cursor supports MCP servers natively via HTTP. Add to your global config at `~/.cursor/mcp.json` or per-project at `.cursor/mcp.json`:
|
|
|
|
```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`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"honcho": {
|
|
"serverUrl": "https://mcp.honcho.dev",
|
|
"headers": {
|
|
"Authorization": "Bearer hch-your-key-here"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
<Note>
|
|
Windsurf uses `serverUrl` instead of `url`.
|
|
</Note>
|
|
|
|
### VS Code (Copilot Chat)
|
|
|
|
Add to your workspace `.vscode/mcp.json`:
|
|
|
|
```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)"):
|
|
|
|
```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:
|
|
|
|
<Tabs>
|
|
<Tab title="macOS">
|
|
`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
|
|
</Tab>
|
|
<Tab title="Windows">
|
|
`%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
```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`:
|
|
|
|
```json
|
|
{
|
|
"context_servers": {
|
|
"honcho": {
|
|
"url": "https://mcp.honcho.dev",
|
|
"headers": {
|
|
"Authorization": "Bearer hch-your-key-here"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
<Note>
|
|
Zed uses `context_servers` instead of `mcpServers`. Native HTTP support requires Zed v0.214.5 or later.
|
|
</Note>
|
|
|
|
### Goose
|
|
|
|
[Goose](https://goose-docs.ai/) 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`):
|
|
|
|
```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
|
|
```
|
|
|
|
<Tip>
|
|
To teach Goose the recommended memory flow, save the [instructions](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md) 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`.
|
|
</Tip>
|
|
|
|
---
|
|
|
|
## 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](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md).
|
|
|
|
---
|
|
|
|
## 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](https://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](https://discord.gg/honcho) or open an issue on [GitHub](https://github.com/plastic-labs/honcho/tree/main/mcp).
|