Integration Tutorials

MCP host integration

Wire Roam into your MCP-aware coding agent in one line. The roam mcp-setup generator reads the live tool registry, so the JSON it emits always matches what roam mcp actually exposes — hand-rolled snippets drift the moment the preset or tool list changes. See Generate config: don't hand-edit for the full rationale.

Generator targets (live _CONFIGS list): claude-code, cursor, windsurf, vscode, gemini-cli, codex-cli. Amp (Sourcegraph) uses the same JSON shape but is added through Amp's own MCP settings panel.

Quick Setup Matrix

Claude Code

1. Register Roam as an 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

CI/CD pipeline integration

Generate a ready-to-commit pipeline for your CI platform. The emitted template runs roam health, roam check-rules, and roam pr-risk on every pull request, posts a sticky comment, and (on GitHub) uploads SARIF to Code Scanning so findings surface in the PR diff UI.

roam ci-setup                          # auto-detect platform
roam ci-setup --platform github --write
roam ci-setup --platform gitlab --gate 70 --write
roam --json ci-setup --platform azure  # structured envelope

Supported platforms: github, gitlab, azure, jenkins, bitbucket. The GitHub Actions template surfaces Roam findings to Code Scanning via SARIF 2.1.0:

roam --sarif health > roam-health.sarif
# Upload via github/codeql-action/upload-sarif in the generated workflow.

Opt into supply-chain attestation with --with-slsa-l3. The flag emits a second workflow (.github/workflows/roam-slsa-src-l3.yml) that runs roam pr-bundle emit --slsa-l3 --sign --keyless on every PR — OIDC-anchored cosign signature plus a VSA-shaped predicate, lifting the assurance floor from SRC-L2 to SRC-L3. GitHub-only in v1 (Fulcio + Rekor wire-up). After the workflow is in place, sanity-check the local roam install with roam doctor; it surfaces missing index, stale schema, or missing optional extras before the first CI run.

Also bundled (drop-in samples, not auto-emitted by ci-setup): agent-review.yml for roam pr-analyze on every PR, and roam-sarif-with-codeql.yml for running Roam SARIF alongside CodeQL. Sources ship inside the wheel at src/roam/templates/ci/.

MCP gateway integration

Gateway operators (Interlock, Lasso, Portkey, custom) consume two structured evidence streams Roam emits per agent session: the per-tool-call McpDecisionReceipt and the HMAC-chained run ledger under .roam/runs/. Roam is the inside-server half of the trust boundary; the gateway owns network policy, prompt-injection scanning, and audit aggregation. The split is summarised on MCP security stance and discussed in full on Discussion #37.

Export the receipt schema (JSON Schema Draft 2020-12) for validator wire-up:

python scripts/export_mcp_receipt_schema.py > mcp-receipt.schema.json

The schema is reconstructed at export time from the closed-enum vocabulary in roam.evidence._vocabulary, so a vocabulary change propagates without manual edits. Each receipt records actor identity, tool id, sha256 of inputs, policy verdict (allow / deny / escalate / redact / not_evaluated), and a hash of outputs — raw payloads are never stored, only digests.

Verify the run ledger offline with roam runs verify (4-state verdict: ok, tampered, unsigned, key_missing; exit 5 on tampered so CI can gate on integrity):

roam runs verify                       # last run
roam runs verify <run_id>
roam runs verify --all                 # every run in this repo

For the full gateway-vs-inside-server framing, see dev/MCP-SECURITY-POSTURE.md in the repo — the long-form posture document the public docs condense.

OSCAL audit integration

Emit an OSCAL v1.2 Control Mapping or Assessment Results document for downstream GRC tooling. Roam maps to and supports evidence for the controls in the bundled crosswalk; it does not certify a customer compliant. The crosswalk lives in the wheel at src/roam/templates/audit_report/control-mapping.yaml and is honoured as an override when present at the project root.

roam evidence-oscal --kind control-mapping > oscal-controls.json
roam evidence-oscal --kind assessment-results --evidence change-evidence.json \
  --import-ap-ref oscal-ap.json > oscal-results.json

Persist the OSCAL artefacts on disk with roam ci-setup --with-oscal; the flag materialises .roam/oscal/control-mapping.json and a stub assessment-plan.json so subsequent roam evidence-oscal --kind assessment-results calls can pass --import-ap-ref instead of synthesising the stub inline. The eight evidence questions an Assessment Results document answers are catalogued on Architecture — The eight evidence questions; the corresponding ChangeEvidence packet shape is summarised on PR Replay — Eight questions every packet answers.

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.

See also

• Full surface reference: Command Reference — every command, every flag, every JSON envelope.
• MCP security stance: Inside-server vs gateway — what Roam owns and what your MCP host owns.
• Config generator rationale: Generate config: don't hand-edit — why roam mcp-setup is the source of truth.
• Eight evidence questions: Architecture — how the graph, findings registry, run ledger, and evidence compiler fit together.
• Agent contract: Agent Contract — context before edit, impact before delete, critique before merge.
• Worked example on your own repo: PR Replay — Eight questions every packet answers — we replay your last 5 PRs through Roam, return a signed evidence packet plus a written analyst report, and your spend converts to Review credit if you continue with the hosted product.