MCP server — User guide

Home · Docs · Quick start · Install

stdio MCP server — CIL for AI agents on top of a local Project Intelligence Layer (PIL).

Connect once to Claude Code, Cursor Agent, Codex, Gemini CLI, or VS Code MCP. Agents can ask_project, inspect state, capture decisions, and transfer context — without you re-explaining architecture every session.

Normal use: configure once, open your AI tool in the project folder — the host starts MCP automatically.

CIL tools (questions and narratives)

Natural-language and narrative queries route through Cognitive Kernel:

ask_project · get_next_actions · get_cognitive_health · get_entity_knowledge
get_project_essence · get_handoff_replay · get_snapshot · get_decision_graph
get_project_history · transfer_story · transfer_project · get_suggested_questions

CLI mirror: contorium ask · contorium health · contorium transfer --mode=…

See CIL v3 spec (GitHub) · Surfaces (GitHub).

AI Layer tools (optional — default off)

Explanation-layer LLM status and connectivity. Fact/PIL tools do not require LLM.

Configure via contorium ai setup, CLI dashboard View E (LLM Config), or IDE contora.cilAiEnabled. Keys: .contora/config/.llm-keys.json (per provider).

See AI Layer (GitHub).

Before you start

Main MCP tools

Ask (CIL — recommended first)

Natural-language queries route through the Cognitive Kernel. CIL suggests and explains — it never executes tasks.

CLI mirror: contorium ask "…" · contorium health · contorium transfer --mode=story

PIL (Inspect · Transfer · Capture)

On a new AI chat, the agent may ask to inject project state (Y/n). No terminal command needed.

Connect your AI tool

Run one command from your project folder, then open the AI tool in that folder.
Node.js 18+ required. No JSON editing needed in normal use.

Codex

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

Open Codex in the project folder. Remove: codex mcp remove contorium

Claude Code

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

Restart Claude Code in the same folder. Remove: claude mcp remove contorium

Cursor

1. Settings → MCP → Add MCP Server
2. Name: contorium · Command: npx · Args: @contorium/mcp
3. Enable the server → Developer: Reload Window

Remove: Settings → MCP → delete contorium

Gemini CLI

Add to ~/.gemini/settings.json or <project>/.gemini/settings.json:

{
  "mcpServers": {
    "contorium": {
      "command": "npx",
      "args": ["@contorium/mcp"],
      "env": {
        "CONTORIUM_WORKSPACE": "/path/to/your-project"
      }
    }
  }
}

Restart the Gemini CLI session after saving.

Manual config (fallback only)

Use this only if the one-liner above fails. Do not combine with mcp add.

{
  "mcpServers": {
    "contorium": {
      "command": "npx",
      "args": ["@contorium/mcp"],
      "env": {
        "CONTORIUM_WORKSPACE": "/path/to/your-project"
      }
    }
  }
}

How MCP runs (important)

You open Codex / Claude Code / Cursor Agent
        ↓
Host reads .mcp.json / MCP settings
        ↓
Host spawns: npx @contorium/mcp   (or node …/contorium-mcp.js)
        ↓
MCP connects over stdio
        ↓
On initialize: bootstrap runtime + semi-auto handoff prompt (user confirm)
        ↓
AI calls tools (get_project_handoff, …) when needed

Workspace resolution

The server resolves the project root in this order:

1. CLI flag: --workspace /path/to/project
2. Environment: CONTORIUM_WORKSPACE (also CODEX_PROJECT_DIR, CLAUDE_PROJECT_DIR, CLAUDE_PROJECT_ROOT, MCP_WORKSPACE_ROOT)
3. .mcp.json or .cursor/mcp.json → mcpServers.contorium.env.CONTORIUM_WORKSPACE
4. Walk up from cwd to find .contora/state.json

Decision Provenance tools (preferred)

Single decision pipeline shared with IDE and CLI. Artifacts persist under .contora/governance/.
See GitHub language spec.

Semantic separation:

• Review-only flows write review.json
• derive_decision_provenance writes decision / scope / trace / cycle (and optional trace-full)

Legacy governance tool aliases

Governance auxiliary tools

Cognitive mode tools (A/B)

Mode B overlay suggests skills from open sources (GitHub, npm, local registry). Display-only — nothing is auto-installed. Switch modes from the runtime dashboard (↑↓ select, Enter apply) or via MCP tools.

Semi-Auto Context Injection (automatic — no CLI command)

When runtime is active and the host opens a new AI chat (new MCP stdio session):

1. MCP initialize calls prepareHandoffInjection({ newChat: true }) → pending state.
2. Server instructions tell the Agent to call get_handoff_injection_status and ask the user Y/n.
3. User confirms via UI (no command):
   - Terminal dashboard: [?] on Passive line → Enter/i · n
   - IDE: auto notification + status bar [?] Inject runtime?
   - Agent: confirm_handoff_injection / skip_handoff_injection
4. On confirm → .contora/mcp.auto-context.md + clipboard (IDE).

Debug only: contorium handoff --prompt-new-chat (TTY fallback).

Each new chat re-prompts; skip/inject applies to the current chat only (chat_session_id).

Runtime bootstrap (automatic)

When MCP starts, it schedules (via CLI adapter, detached):

• contorium bootstrap --source mcp — sync + Passive dashboard worker
• MCP light sync — 5s poll + watch on .contora/events and .git/HEAD
• Dashboard wake on file/git changes

See Runtime dashboard. No manual contorium attach in normal use.

Environment variables

Uninstall / disable

Clear MCP-only memory (optional, project root):

Remove-Item -Recurse -Force .contora\mcp -ErrorAction SilentlyContinue

Does not remove state.json, handoff.json, or other shared artifacts.

Troubleshooting