Skip to content

MCP_CLIENTS.md

Latest commit

 

History

History
205 lines (152 loc) · 6.89 KB

MCP_CLIENTS.md

File metadata and controls

205 lines (152 loc) · 6.89 KB
Raw

Cognitive Castle in your MCP client

Castle ships an MCP server (castle-mcp) that any Model Context Protocol client can consume. The result is the same in every host: your AI agent gets castle_* tools in its tool palette and can read/write your local palace during conversation.

Claude Code and Codex have dedicated plugins with MCP tools and conversation capture hooks. Codex also bundles a recall/remember skill; follow the Codex plugin setup guide for installation and hook activation. Other MCP clients can register castle-mcp directly for memory tools.

Install prerequisites once

git clone https://github.com/Testimonial/cognitive-castle.git
cd cognitive-castle
pip install -e .
# Verify the entry points landed on PATH
which castle && which castle-mcp

Initialize a palace once (per project or globally):

castle init ~/projects/myapp --yes

Everything below assumes castle-mcp is on your $PATH.

Claude Code (highest-fidelity — full plugin experience)

/plugin marketplace add Testimonial/cognitive-castle
/plugin install castle@cognitive-castle
# then fully quit and reopen Claude Code

That's it. MCP tools + Stop/PreCompact hooks + slash commands (/castle:init, /castle:mine, /castle:search, /castle:status, /castle:help) are all wired.

Manual alternative (if you prefer not to use the plugin marketplace):

claude mcp add castle -- castle-mcp

Codex (OpenAI's coding CLI)

For MCP tools, the castle skill, and automatic transcript capture, install the cognitive-castle plugin using the step-by-step guide. It covers PATH setup, the personal marketplace, /hooks trust, /mcp, updates, and verifying a saved conversation. In /hooks, select an event such as Stop to see the plugin name in its details.

For tools only, Codex also reads MCP servers from ~/.codex/config.toml. Use this as an alternative to the bundled plugin registration:

[mcp_servers.castle]
command = "castle-mcp"

Restart Codex. The 32 castle_* tools appear in the tool palette.

Sharing knowledge with Claude Code (recommended)

Castle stores everything in one LanceDB palace at ~/.castle/palace/. Both clients can point at the same palace and the reads/writes go to the same tables — anything Claude Code files is instantly visible in Codex, and vice-versa.

To pin the palace explicitly (safer if you ever run more than one):

[mcp_servers.castle]
command = "castle-mcp"
args = ["--palace", "/home/YOU/.castle/palace"]

And the matching Claude Code registration:

claude mcp add castle -- castle-mcp --palace /home/YOU/.castle/palace

Both clients now write to the same LanceDB tables, so the palace is a single shared memory across your Codex + Claude Code sessions.

Verifying the two clients see the same data

Quick round-trip smoke test:

  1. From Claude Code, ask its agent to file a distinctive drawer:

    "Use castle_add_drawer to file wing=cross_check, room=test, content='canary 2026-07-26'"

  2. From Codex, search for it:

    "Use castle_search to find 'canary 2026-07-26'"

If Codex retrieves the exact string Claude Code saved, both are wired to the same palace.

Automatic capture with the Codex plugin

After trusting the plugin's Stop and PreCompact hooks, Codex captures the current transcript in the background under a codex_<workspace-name> wing. MCP-only registration does not enable capture. See hook activation and save verification.

Env vars propagate

CASTLE_EMBEDDER_MODEL, CASTLE_PROJECT, CASTLE_LLM_* etc. that you set in your shell are inherited by the castle-mcp subprocess Codex launches. If you set them for one client, keep them in a shared shell profile (~/.bashrc / ~/.zshrc) so Claude Code sees the same values — otherwise you can hit EmbedderIdentityMismatchError on the first search from the mismatched client.

Cursor

Cursor supports MCP via .cursor/mcp.json (per-workspace) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "castle": { "command": "castle-mcp" }
  }
}

Reopen Cursor. Verify with the tool palette in a chat panel — you should see castle_search, castle_status, castle_add_drawer, castle_info_score, and friends.

VS Code + GitHub Copilot

Modern GitHub Copilot Chat in VS Code supports MCP servers via workspace-level .vscode/mcp.json or user-level settings. Add:

{
  "mcpServers": {
    "castle": { "command": "castle-mcp" }
  }
}

Reload the VS Code window. The tools show up in the Copilot Chat tool picker under the castle prefix.

Older Copilot builds without MCP support cannot consume Castle — the Claude Code plugin, Codex, or Cursor path is the fallback.

Gemini CLI

See examples/gemini_cli_setup.md — same pattern (castle-mcp as the MCP server binary in Gemini CLI's server config).

Generic MCP client (anything else)

Any MCP client that supports the standard mcpServers config block works. The one line that matters everywhere is:

{ "mcpServers": { "castle": { "command": "castle-mcp" } } }

Environment variables (e.g. CASTLE_LLM_PROVIDER, CASTLE_PROJECT) propagate to the subprocess exactly as they would to any child process launched by the host.

What tools your client will see

  • Read: castle_status, castle_list_wings, castle_list_rooms, castle_get_taxonomy, castle_search, castle_check_duplicate, castle_info_score (v3.4.0 — nn_novelty score for arbitrary text)
  • Write: castle_add_drawer, castle_delete_drawer
  • Knowledge graph: castle_traverse_graph, castle_find_tunnels, castle_create_tunnel, castle_list_tunnels, castle_delete_tunnel, castle_follow_tunnels, castle_graph_stats
  • Diary: castle_diary_write, castle_diary_read
  • Maintenance: castle_reconnect, castle_kg_invalidate
  • Discovery: castle_get_aaak_spec

Full schema for each is emitted by the tools/list MCP call your client makes at connection time.

Feature parity matrix

Feature Claude Code Codex Cursor VS Code+Copilot Gemini CLI Generic MCP
castle_* MCP tools ✅ ✅ ✅ ✅ (recent) ✅ ✅
Slash commands (/castle:*) ✅ ❌ ❌ ❌ ❌ ❌
Auto-mining Stop/PreCompact hooks ✅ ✅ (trusted plugin) ❌ ❌ ❌ ❌
MCP initialize.instructions injection ✅ ✅ (if client honours it) ⚠️ ⚠️ ⚠️ depends
Skill loading ✅ ✅ (plugin) ❌ ❌ ❌ ❌

Claude Code and Codex plugins provide tools and capture hooks. Codex requires explicit hook review after installation and when definitions change. Clients configured only with an MCP server need an explicit castle mine invocation or their own capture integration to import conversations.