stdio MCP server

Contorium MCP Server

Runtime memory tools for Codex, Claude Code, and Cursor Agent. Complements the Contorium VSIX—use MCP when the agent runs without the sidebar UI.

Before you start

  1. Install the Contorium extension VS Code Marketplace or Open VSX. MCP reads workspace state the extension writes under .contora/.
  2. Open your project Contorium begins tracking active files, edits, and Git changes into workspace memory.
  3. Set your current focus (recommended) Example: Refactor payment retry system — memory builders rank context around that intent.
  4. Build the MCP server From the Contorium repo. Portable entry: bin/contorium-mcp-launch.cjs.

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

Agents call these tools over stdio—no manual copy-paste of workspace context.

Tool Description
store_memory Persist key/value memory under .contora/mcp/memories.json
search_memory Keyword search over MCP memory entries
get_memory Fetch one entry by key
get_workspace_context Read .contora/state.json from the extension (focus, Git, files)

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. Open your project Extension tracks active files, edits, and Git into .contora/.
  2. Set current focus e.g. Refactor payment retry system — inferred goals and ranked files update automatically.
  3. Work normally Memory builders run continuously; event history and compression stay within token budgets.
  4. Let agents use MCP Codex / Claude Code agents call get_workspace_context and memory tools—or use sidebar Copy AI-ready context for one-click export.

On-disk layout

<workspace-root>/
├── .contoraignore
└── .contora/
    ├── state.json       # extension snapshot (MCP reads)
    ├── events/
    ├── last-intent.json
    ├── memory/
    └── mcp/
        └── memories.json # MCP store_memory

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

Extension vs MCP

VS Code / Cursor extension
  • Sidebar: focus, goals, Git, active files
  • Workspace scanner & memory builder
  • Session save / restore
  • Copy AI-ready context (clipboard export)
MCP server
  • Agent-callable tools (Codex, Claude Code)
  • get_workspace_context from state.json
  • store_memory / search_memory / get_memory
  • stdio — no duplicate UI layer

Internal extension command and config IDs remain contora.*; display name is Contorium.

docs/MCP.md Product README GitHub

Connect your agents to workspace memory

Install the extension, run npm run build:mcp, then wire Claude Code MCP.

Installation guide Back to home