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}",
        "--header",
        "X-Honcho-User-Name:${USER_NAME}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your-honcho-key>",
        "USER_NAME": "<your-name>"
      }
    }
  }
}

Optional Headers

Header	Default	Description
X-Honcho-Assistant-Name	"Assistant"	Name for the assistant peer
X-Honcho-Workspace-ID	"default"	Workspace to operate in
X-Honcho-Base-URL	https://api.honcho.dev	Custom API base URL

Available Tools

Bespoke Flow (Simple)

Tool	Description
start_conversation	Start a new conversation, returns a session ID
get_personalization_insights	Ask Honcho about the user for personalized responses
add_turn	Record user + assistant messages

General Tools

Workspace: search_workspace, get_workspace_metadata, set_workspace_metadata

Peers: create_peer, list_peers, chat, get_peer_card, set_peer_card, get_peer_context, get_representation, get_peer_metadata, set_peer_metadata, search_peer_messages

Sessions: create_session, list_sessions, delete_session, clone_session, add_peers_to_session, remove_peers_from_session, get_session_peers, add_messages_to_session, get_session_messages, search_session_messages, get_session_context, get_session_representation, get_session_metadata, set_session_metadata

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(), createClient()
  types.ts              # ToolContext, result helpers
  tools/
    bespoke.ts          # start_conversation, add_turn, get_personalization_insights
    workspace.ts        # search, metadata
    peers.ts            # CRUD, chat, card, context, representation, search
    sessions.ts         # CRUD, peers, messages, context, representation, 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

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>" \
  --header "X-Honcho-User-Name:test"

Deploy

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