MCP session view · V3.1 · 18 tools

Contorium MCP Server

MCP tools for Codex, Claude Code, Cursor Agent, and Gemini CLI. A peer session view over the same .contora/ state — can bootstrap without the IDE extension.

Before you start

  1. Build from source npm install && npm run compile in the Contorium repo. Portable entry: bin/contorium-mcp-launch.cjs.
  2. Set workspace root Use CONTORIUM_WORKSPACE env var pointing at your project folder.
  3. IDE extension (optional, recommended) Adds event-driven precision. MCP alone still bootstraps .contora/ via scan. IDE docs
  4. Configure your agent host Codex, Claude Code, Cursor, or Gemini — see sections below.

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

Build

From the Contorium repository root. Installs packages/mcp dependencies automatically.

Repository root
git clone https://github.com/ContoriumLabs/contorium.git
cd contorium
npm install

npm run build:mcp
# or: npm run compile

# First-time optional:
npm run install:mcp
  • Portable entry: bin/contorium-mcp-launch.cjs
  • stdio entry: packages/mcp/dist/server.js (after build)
  • Also runs via: npm run compile (sync + runtime + MCP + extension)

docs/MCP.md Install extensions

Codex

After npm run build:mcp, add Contorium MCP to Codex. Plugin manifest: .codex-plugin/plugin.json · MCP: .mcp.json.

Codex MCP
npm run build:mcp
codex mcp add contorium -- node ./bin/contorium-mcp-launch.cjs

Install as a Codex plugin: Codex plugins docs. See .agents/plugins/marketplace.example.json in the Contorium repo for a local marketplace example.

Claude Code

See docs/MCP.md. Uses .claude-plugin/plugin.json and .mcp.claude.json. After npm run build:mcp:

Option A — Load plugin locally

claude --plugin-dir .

Option B — MCP only (project scope)

claude mcp add --scope project contorium \
  -- node ./bin/contorium-mcp-launch.cjs

Plugin MCP config uses ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PROJECT_DIR} (see .mcp.claude.json in the repo).

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 Agent (MCP)

Coming soon.

Detailed Cursor Agent MCP wiring will be added here. The repo ships root mcp.json (see platform table above). For now: install the Contorium VSIX, or use Codex / Claude Code MCP flows.

MCP tools (V3.1)

Agents call these tools over stdio. Recommended execution entry: get_project_handoff. Cognitive summary: get_project_graph_snapshot.

Tool R/W Description
get_project_handoff R V3.1 recommended AI execution entry — .contora/handoff.json
get_project_graph_snapshot R V3.1 cognitive summary — .contora/graph/snapshot.json
get_project_knowledge_graph R Full cognitive graph; default minConfidence 0.7
get_project_snapshot R L4 Markdown snapshot; optional format=json
get_workspace_context R state.json — focus, Git, active files
get_project_change R V3.1 change semantics — .contora/change.json
get_project_graph R Change neighborhood — .contora/graph.json
get_project_timeline R Code evolution — .contora/timeline.json
store_memory W Persist to .contora/mcp/memories.json
search_memory / get_memory R MCP memory search and fetch
get_project_intelligence R L5 intelligence/state-summary.json
get_intent_graph / get_active_intents R L5 intent graph (sidebar preview; not in main copy export)
get_project_state R L4 state-builder/project-state.json
get_state_conflicts R v2 unresolved conflicts (audit only)

Deprecated: get_project_impact, get_project_intent — use get_project_handoff instead. Full reference: docs/MCP.md.

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

  1. Set workspace root Configure CONTORIUM_WORKSPACE to your project folder.
  2. Bootstrap or sync state MCP bootstraps .contora/ on first call; IDE extension adds event-driven precision (optional).
  3. Set current focus (IDE, optional) e.g. Refactor payment retry system — ranks files and snapshot around that intent.
  4. Agents call MCP tools Prefer get_project_handoff or get_project_graph_snapshot; also get_project_snapshot, get_workspace_context, store_memory — or use IDE Copy AI-ready context for clipboard export.

On-disk layout

<workspace-root>/
└── .contora/
    ├── state.json       # workspace truth (all views read)
    ├── graph/           # V3.1 knowledge + snapshot + hotspots
    ├── handoff.json     # AI execution entry
    ├── events/          # IDE session view writes
    ├── state-builder/
    └── mcp/
        └── memories.json # store_memory

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.md Product README GitHub

Connect agents to shared workspace state

Run npm run compile, configure MCP, then wire Codex or Claude Code.

Installation guide Back to home