Adoption

Integration Tutorials (5 Platforms)

End-to-end setup and daily workflow for MCP-enabled coding agents. Goal: make the first successful query fast, then standardize a repeatable loop for structural analysis.

Scope: Claude Code, Cursor, Gemini CLI, Codex CLI, and Amp (Sourcegraph). Non-goal: cloud-hosted roam deployment.

Quick Setup Matrix

Platform	Fast setup command	Config fallback
Claude Code	`roam mcp-setup claude-code`	`.mcp.json` in project root
Cursor	`roam mcp-setup cursor`	`.cursor/mcp.json`
Gemini CLI	`roam mcp-setup gemini-cli`	`~/.gemini/settings.json`
Codex CLI	`roam mcp-setup codex-cli`	`~/.codex/config.json` or CLI flag
Amp (Sourcegraph)	Manual stdio entry	Amp MCP settings with command `roam mcp`

Claude Code

1. Register roam MCP server

roam mcp-setup claude-code
claude mcp add roam-code -- roam mcp

2. Verify tool visibility

roam mcp --list-tools
ROAM_MCP_PRESET=core roam mcp

3. First end-to-end workflow

roam init
roam context PaymentService
roam impact PaymentService
roam preflight PaymentService

Cursor

1. Generate MCP config snippet

roam mcp-setup cursor

2. Add generated JSON to Cursor MCP config

Place the emitted config at .cursor/mcp.json in your project.

3. Agent workflow loop

roam init
roam understand
roam check-rules --severity error
roam health --gate

Gemini CLI

1. Generate Gemini MCP config

roam mcp-setup gemini-cli

2. Install into Gemini settings

Merge emitted JSON into ~/.gemini/settings.json.

3. Recommended first session

roam init
roam search-semantic "authentication flow"
roam trace AuthController AuthRepository
roam test-gaps --changed

Codex CLI

1. Configure via command or config file

roam mcp-setup codex-cli
codex --mcp roam-code="roam mcp"

2. Persist config (optional)

Add emitted JSON to ~/.codex/config.json for repeat sessions.

3. Refactor-safe loop

roam init
roam suggest-refactoring --limit 10
roam plan-refactor PaymentService
roam debt --roi

Amp (Sourcegraph)

1. Add a stdio MCP server entry

In Amp MCP settings, register a server named roam-code with command roam and args ["mcp"].

{
  "mcpServers": {
    "roam-code": {
      "command": "roam",
      "args": ["mcp"]
    }
  }
}

2. Validate and run a first path

roam init
roam mcp --list-tools
roam deps src/
roam layers

Cross-Platform Validation Checklist

roam mcp --list-tools shows non-empty tool output.
roam context <symbol> returns ranked files/lines.
roam check-rules runs without configuration errors.
roam health --gate returns deterministic gate output.