refactor: MCP server improvements (plastic-labs#379)

* refactor: MCP server improvements

* feat: add missing tools and polish descriptions. Add inspect_workspace, list_workspaces, inspect_session, get_session_message, and get_session_summaries tools. Fix CORS preflight handling and default route path. Extract shared formatting helpers for messages and summaries. Trim redundant tool descriptions.

* chore: cr updates

* chore: cr

* fix: adding pagnation

* fix: use nanoid to match Honcho's server-side ID format

* fix: simplified tool list. 10 removed, in favor of more unified tools

* docs: clarifying language

* docs: updating agentic dev & MCP.mdx docs

* docs: minor fix

* fix: adding codex

* chore: updating with latest SDK

* docs: update

* fix: adding assistantName config

* chore: clarifying language

---------

Co-authored-by: ajspig <dragon@monstercode.com>

Author: dr-frmr

docs/v3/documentation/introduction/vibecoding.mdx

@@ -1,28 +1,79 @@
 ---
-title: "AI-Powered Honcho Setup"
+title: "Agentic Development"
 icon: "wand-magic-sparkles"
-description: "Agent skills and starter prompt for building with Honcho"
-sidebarTitle: 'Vibecoding Setup'
+description: "Agent skills, MCP server, and tools for building with Honcho"
+sidebarTitle: 'Agentic Development'
 ---
 
-These docs are designed to be easily consumable by LLMs. Each page has a button that lets you copy the page as Markdown or paste directly into ChatGPT or Claude.
 
-We follow the llms.txt standard. There are both an llms.txt and llms-full.txt available:
+## MCP Server
 
-- [llms.txt](/llms.txt)
-- [llms-full.txt](/llms-full.txt)
+The fastest way to give any AI tool persistent memory is through the Honcho MCP server. It works with any client that supports the Model Context Protocol.
+
+**Get started in 2 minutes:**
+
+1. Get an API key at [app.honcho.dev](https://app.honcho.dev)
+2. Add the config for your client below
+3. Restart your client
+
+See the [full MCP documentation](/v3/guides/integrations/mcp) for all available tools, advanced configuration, and setup instructions for every supported client.
+
+<CodeGroup>
+```json Claude Desktop
+{
+  "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"
+      }
+    }
+  }
+}
+```
+
+```json Cursor
+{
+  "mcpServers": {
+    "honcho": {
+      "url": "https://mcp.honcho.dev",
+      "headers": {
+        "Authorization": "Bearer hch-your-key-here",
+        "X-Honcho-User-Name": "YourName"
+      }
+    }
+  }
+}
+```
+
+```bash Claude Code
+claude mcp add honcho \
+  --transport http \
+  --url "https://mcp.honcho.dev" \
+  --header "Authorization: Bearer hch-your-key-here" \
+  --header "X-Honcho-User-Name: YourName"
+```
+</CodeGroup>
 
 ---
 
 ## Claude Code Plugin
 
-
-Use Honcho to build with Honcho! The [plugin](/v3/guides/integrations/claudecode) provides claude code persistent memory that survives context wipes and session restarts.
+Use Honcho to build with Honcho! The [plugin](/v3/guides/integrations/claudecode) provides Claude Code persistent memory that survives context wipes and session restarts.
 
 ```bash
 /plugin marketplace add plastic-labs/claude-honcho
-/plugin install honcho@honcho # Tools for Claude to use Honcho to manage it's own context
-/plugin install honcho-dev@honcho # Skills to teach claude how to integrate Honcho
+/plugin install honcho@honcho # Tools for Claude to use Honcho to manage its own context
+/plugin install honcho-dev@honcho # Skills to teach Claude how to integrate Honcho
 ```
 
 The marketplace also includes all the agent skills below, so you can use `/honcho-dev:integrate` directly after installing.

docs/v3/guides/integrations/mcp.mdx

@@ -1,19 +1,33 @@
 ---
 title: "Model Context Protocol (MCP)"
 icon: 'star-of-life'
-description: "Use Honcho in Claude Desktop"
+description: "Give any AI tool persistent memory with the Honcho MCP server"
 sidebarTitle: 'MCP'
 ---
 
-You can let Claude use Honcho to manage its own memory in the native desktop app by using the Honcho MCP integration! Follow these steps:
+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.
 
-1. Go to https://app.honcho.dev and get an API key. Then go to Claude Desktop and navigate to custom MCP servers.
+**Server URL:** `https://mcp.honcho.dev`
 
 <Note>
-If you don't have node installed you will need to do that. Claude Desktop or Claude Code can help!
+You'll need an API key from [app.honcho.dev](https://app.honcho.dev) to use the hosted MCP server.
 </Note>
 
-2. Add Honcho to your Claude desktop config. You must provide a username for Honcho to refer to you as -- preferably what you want Claude to actually call you.
+## 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": {
@@ -28,15 +42,202 @@ If you don't have node installed you will need to do that. Claude Desktop or Cla
         "X-Honcho-User-Name:${USER_NAME}"
       ],
       "env": {
-        "AUTH_HEADER": "Bearer <your-honcho-key>",
-        "USER_NAME": "<your-name>"
+        "AUTH_HEADER": "Bearer hch-your-key-here",
+        "USER_NAME": "YourName"
       }
     }
   }
 }
 ```
 
-You may customize your assistant name and/or workspace ID. Both are optional.
+<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>
+
+---
+
+## 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
 {
@@ -56,18 +257,52 @@ You may customize your assistant name and/or workspace ID. Both are optional.
         "X-Honcho-Workspace-ID:${WORKSPACE_ID}"
       ],
       "env": {
-        "AUTH_HEADER": "Bearer <your-honcho-key>",
-        "USER_NAME": "<your-name>",
-        "ASSISTANT_NAME": "<your-assistant-name>",
-        "WORKSPACE_ID": "<your-custom-workspace-id>"
+        "AUTH_HEADER": "Bearer hch-your-key-here",
+        "USER_NAME": "YourName",
+        "ASSISTANT_NAME": "Claude",
+        "WORKSPACE_ID": "my-project"
       }
     }
   }
 }
 ```
 
-3. Restart the Claude Desktop app. Upon relaunch, it should start Honcho and the tools should be available!
+---
+
+## 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
 
-4. Finally, Claude needs instructions on how to use Honcho. The Desktop app doesn't allow you to add system prompts directly, but you can 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.
+| 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. |
 
-Claude should then query for insights before responding and write your messages to storage! If you come up with more creative ways to get Claude to manage its own memory with Honcho, feel free to [let us know](https://discord.gg/plasticlabs) or make a PR on this [repo](https://github.com/plastic-labs/honcho/tree/main/mcp)!
+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).