@contorium/mcp · CIL v3 · ask_project · auto-spawn

Install CIL via MCP

Configure once — Codex, Claude Code, Cursor, and Gemini CLI spawn MCP automatically. Agents can ask_project and use CIL tools for history, decisions, and transfer — without you re-explaining architecture every session. See Full MCP guide · Quick start.

Setup in 2 steps

  1. Connect once Run one command for your AI tool (Codex / Claude / Cursor below). No JSON file needed.
  2. Open your AI tool Work in your project folder — the host spawns MCP automatically. You do not run MCP in a terminal daily.

Pick either automatic setup or manual config — not both. Manual JSON is a fallback only — see docs/mcp.html.

Platforms

Platform Plugin manifest MCP config
Codex .codex-plugin/plugin.json .mcp.json
Claude Code .claude-plugin/plugin.json .mcp.claude.json
Cursor .cursor-plugin/plugin.json mcp.json

Connect by platform

Run from your project folder. Node.js 18+ required (for npx).

Codex
cd /path/to/your-project
codex mcp add contorium -- npx @contorium/mcp
Claude Code
cd /path/to/your-project
claude mcp add --scope project contorium -- npx @contorium/mcp

Full MCP guide Manual config fallback

Codex

One command from your project folder. Codex sets the project path automatically.

Codex
cd /path/to/your-project
codex mcp add contorium -- npx @contorium/mcp

Remove: codex mcp remove contorium · Fallback JSON: docs/mcp.html

Claude Code

One command from your project folder. Claude injects CLAUDE_PROJECT_DIR automatically. See docs/mcp.html for plugin and project-scope options. 

cd /path/to/your-project
claude mcp add --scope project contorium -- npx @contorium/mcp

Remove: claude mcp remove contorium

Environment variables

Variable Description
CONTORIUM_WORKSPACE Workspace root (default: cwd, or walk up to find .contora/state.json)
CLAUDE_PROJECT_DIR Set by Claude Code when spawning MCP (preferred for plugin installs)
CLAUDE_PROJECT_ROOT Alias accepted by some integrations

Cursor

Cursor has no mcp add CLI. Use the MCP settings UI (one-time setup):

  1. Settings → MCP → Add MCP Server
  2. Name: contorium
  3. Command: npx
  4. Args: @contorium/mcp
  5. Env (optional): CONTORIUM_WORKSPACE = project root if auto-detect fails
  6. Enable the server → Developer: Reload Window

Remove: Settings → MCP → remove contorium · Or use manual .cursor/mcp.json

Gemini CLI

Add contorium to mcpServers in ~/.gemini/settings.json or <project>/.gemini/settings.json. See configuration template in the full MCP guide.

MCP tools (CHP v1 + Governance V4)

Recommended: get_project_handoff, injection tools, run_governance_cycle, get_understanding_graph. Full catalog in docs/mcp.html.

Tool R/W Description
get_project_handoff R CHP v1 — primary AI execution entry
get_handoff_injection_status R Semi-auto new-chat inject state
confirm_handoff_injection / skip_handoff_injection W User Y/n → writes .contora/mcp.auto-context.md
get_understanding_graph R Call chains + impact — understanding_graph.json
get_recent_changes R File & symbol updates — change.json
get_runtime_state R Bootstrap / dashboard / session (read-only)
run_governance_cycle W Full governance decision cycle → .contora/governance/
export_governance_context R Export governance appendix for AI chat
get_cognitive_mode / set_cognitive_mode R/W Cognitive overlay mode A (default) or B (skill suggestions)
get_project_snapshot R L4 Markdown snapshot (legacy)
get_workspace_context R state.json
store_memory W .contora/mcp/memories.json

Also: get_project_knowledge_graph, get_project_graph_snapshot, get_project_change, get_intent_graph, … — see docs/mcp.html.

Tool examples

store_memory

// Agent stores agent-specific notes
{
  "key": "retry-refactor-goal",
  "value": "Classify retry errors; fix duplicate outbound requests"
}

// Written to .contora/mcp/memories.json

Persist key/value pairs for later agent sessions.

get_memory

// Request
{ "key": "retry-refactor-goal" }

// Response
{
  "key": "retry-refactor-goal",
  "value": "Classify retry errors; fix duplicate outbound requests"
}

Fetch a single MCP memory entry by key.

search_memory

// Request
{ "query": "payment retry" }

// Response
{
  "matches": [
    {
      "key": "retry-refactor-goal",
      "value": "Classify retry errors..."
    }
  ]
}

Keyword search across MCP memory entries.

get_workspace_context

// Reads .contora/state.json (extension)
{
  "focus": "Refactor payment retry system",
  "active_files": ["src/retry.ts", "src/payment.ts"],
  "git": {
    "staged": ["src/retry.ts"],
    "modified": ["src/payment.ts"]
  }
}

Live workspace snapshot: focus, files, Git—from extension scanners.

Typical workflow (automatic)

  1. One-time setup Run codex mcp add or claude mcp add (or Cursor MCP UI) from your project folder.
  2. Open your AI tool Host spawns npx @contorium/mcp, bootstraps .contora/, and attaches the Passive dashboard.
  3. New chat Optional Y/n inject prompt — or Agent calls get_project_handoff when needed.
  4. Governance (optional) Use run_governance_cycle or IDE Review Change; export via export_governance_context or dashboard c.

On-disk layout

<workspace-root>/
└── .contora/
    ├── handoff.json              # CHP v1 AI handoff
    ├── understanding_graph.json  # call chains + impact
    ├── state.json
    ├── change.json / graph.json / timeline.json
    ├── runtime.bootstrap.json
    ├── mcp.auto-context.md
    ├── mcp.handoff-injection.json
    ├── dashboard.*.json
    ├── graph/                    # knowledge, snapshot, hotspots
    ├── governance/               # review, decision, scope, trace, cycle
    ├── events/
    ├── state-builder/
    └── mcp/
        └── memories.json

Export formats (sidebar / settings): markdown, json, cursor, claude, openai — see exportFormat and exportTokenBudget in extension settings.

Session views: IDE vs MCP

IDE session view
  • Sidebar: focus, Git, active files
  • Event-driven workspace scanning
  • Session save / restore
  • Copy AI-ready context (clipboard export)
MCP session view
  • Agent-callable tools (Codex, Claude Code, Gemini)
  • get_project_snapshot / get_workspace_context
  • store_memory / search_memory / get_memory
  • Bootstrap + 5s sync — no sidebar required

Both are peer views over the same .contora/ state — not separate memory systems.

docs/mcp.html Product README GitHub

Connect agents to shared workspace state

Run one command for your AI tool, then open Codex or Claude Code in your project.

Installation guide Back to home