335 lines
9.1 KiB
Plaintext
335 lines
9.1 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}",
|
|
"--header",
|
|
"X-Honcho-User-Name:${USER_NAME}"
|
|
],
|
|
"env": {
|
|
"AUTH_HEADER": "Bearer hch-your-key-here",
|
|
"USER_NAME": "YourName"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
<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" \
|
|
--header "X-Honcho-User-Name: YourName"
|
|
```
|
|
|
|
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",
|
|
"--header",
|
|
"X-Honcho-User-Name:YourName"
|
|
]
|
|
```
|
|
|
|
<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",
|
|
"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`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"honcho": {
|
|
"serverUrl": "https://mcp.honcho.dev",
|
|
"headers": {
|
|
"Authorization": "Bearer hch-your-key-here",
|
|
"X-Honcho-User-Name": "YourName"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
<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",
|
|
"X-Honcho-User-Name": "YourName"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
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",
|
|
"X-Honcho-User-Name": "YourName"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 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",
|
|
"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`:
|
|
|
|
```json
|
|
{
|
|
"context_servers": {
|
|
"honcho": {
|
|
"url": "https://mcp.honcho.dev",
|
|
"headers": {
|
|
"Authorization": "Bearer hch-your-key-here",
|
|
"X-Honcho-User-Name": "YourName"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
<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 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`):
|
|
|
|
```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
|
|
```
|
|
|
|
<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>
|
|
|
|
---
|
|
|
|
## 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):
|
|
|
|
```json
|
|
{
|
|
"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](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md) 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](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).
|