MCP integration

MCP: execution memory for AI assistants

The genos-mcp server exposes GenOS as a Model Context Protocol tool provider. A compatible assistant can manipulate capsules, create isolated branches, run checks, compare outcomes, and inspect provenance without reimplementing the runtime.

assistant / IDE
      │ JSON-RPC + MCP
      ▼
  genos-mcp ── policy, validation, structured results
      │ explicit argv
      ▼
  GenOS CLI ── capsules, worlds, events, CAS, lineage

Two transports

• STDIO: newline-delimited JSON-RPC for local IDEs and assistants;
• Stateless HTTP: POST /mcp for calls and GET /health for supervision.

The server negotiates MCP versions 2025-06-18, 2025-03-26, and 2024-11-05. It implements initialize, tools/list, and tools/call, returning structured GenOS results with the operation, exit code, stdout, stderr, and error state.

Build and connect

cargo build --release -p genos-cli -p genos-mcp

{
  "mcpServers": {
    "genos": {
      "command": "/absolute/path/to/genos-mcp",
      "args": ["stdio"],
      "env": {
        "GENOS_ROOT": "/project/.genos",
        "GENOS_WORKSPACE_ROOT": "/project"
      }
    }
  }
}

The integration guide contains profiles for Codex, VS Code, Claude Desktop, Cline, Roo Code, and JetBrains IDEs. Some source examples still use the older genos mcp spelling; the currently compiled server binary is genos-mcp.

The useful lifecycle

search known failures
        ↓
diagnose falsifiable hypotheses
        ↓
snapshot → competing forks → isolated execution
        ↓
diff + evidence + evaluation
        ↓
recorded decision → controlled merge

Core tools include genos_snapshot, genos_restore, genos_fork, genos_run, genos_diff, genos_lineage, genos_replay, and genos_merge. The wider surface adds diagnosis, hypothesis evidence, negative knowledge, trajectory analysis, and specialized experiments.

genos_search_failures(query="Redis lock timeout")
genos_diagnose(problem="Redis lock timeout", hypotheses=[...])
genos_snapshot(capsule_id="main_active")
genos_fork(capsule_id="main_active", branches=[...])
genos_run(capsule_id="candidate_1", command="cargo test")
genos_diff(a="baseline", b="candidate_1")
genos_record_decision(title="...", evidence=[...])

Approval and safety policy

Tier	Examples	Suggested policy
Read / analyze	inspect, diff, lineage, replay, failure search	Auto-approval can be appropriate
Cognitive mutation	snapshot, fork, diagnosis, decision	Allow writes
Execution	run, workspace experiment, investigation	Require confirmation

The planner builds explicit process arguments instead of concatenating a shell command. Git-worktree worlds separate file mutations. This narrows the attack surface, but it does not replace an OS sandbox for arbitrary untrusted code.

Maintained and research surfaces

The catalogue documents more than forty tools, including resilience, biomimicry, and hallucination families. They do not all have the same maturity. Lifecycle primitives and several development tools are executable; some advanced commands remain protocol contracts, planners, or prototypes. Read the MCP tool reference together with the evidence status.

Verify the MCP layer

cargo test -p genos-mcp
node benchmarks/run-safety-benchmarks.mjs --task B05

The B05 report publishes the tested predicates and remaining limitations.