honcho/mcp

Honcho MCP Server

A Cloudflare Worker that implements the Model Context Protocol (MCP) for Honcho, providing AI memory and personalization tools to LLM clients like Claude Desktop.

Quickstart: Use the Hosted Server

1. Get an API key at https://app.honcho.dev
2. Add Honcho to your Claude Desktop config:

{
  "mcpServers": {
    "honcho": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "https://mcp.honcho.dev",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your-honcho-key>"
      }
    }
  }
}

Every workspace-scoped tool takes a workspace_id argument. If you set X-Honcho-Workspace-ID on the connection, that value fills workspace_id when the argument is omitted. Use list_workspaces to discover IDs.

Available Tools

Workspace: list_workspaces (id, metadata, created_at), create_workspace (get-or-create with optional metadata), inspect_workspace (aggregates metadata, configuration, and peer/session IDs), search (semantic search scoped by optional peer/session params), 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

Architecture

src/
  index.ts              # Worker entry point — parse config, delegate to MCP handler
  server.ts             # createServer() — registers all tools on an McpServer
  config.ts             # HonchoConfig, parseConfig(), createClientFactory()
  types.ts              # ToolContext, result helpers
  tools/
    workspace.ts        # inspect, list, search, metadata
    peers.ts            # CRUD, chat, card, context, representation
    sessions.ts         # CRUD, peers, messages, inspect, context, clone
    conclusions.ts      # list, query, create, delete
    system.ts           # dream, queue status

Built on:

• agents — createMcpHandler for Cloudflare Workers
• @modelcontextprotocol/sdk — McpServer for tool registration
• @honcho-ai/sdk v2 — Honcho TypeScript SDK

Self-Hosted Honcho

If you run Honcho yourself (for privacy, latency, or offline use), deploy the MCP Worker alongside your instance and set HONCHO_API_URL in its environment.

Local dev (bun run dev): create mcp/.dev.vars:

HONCHO_API_URL=http://127.0.0.1:28000

Deployed Worker:

wrangler secret put HONCHO_API_URL
# paste your URL when prompted

When HONCHO_API_URL is unset the Worker routes to https://api.honcho.dev, so this change is backward-compatible.

Development

Setup

bun install

Local dev

bun dev

Type-check

bun run tsc --noEmit

Test locally

bunx mcp-remote http://localhost:8787 \
  --header "Authorization:Bearer <key>"

Deploy

bun run deploy              # production
bun run deploy:staging      # staging