Skip to content

Adoption

# Integration Tutorials

End-to-end setup for the three audiences that integrate Roam: MCP host authors (Claude Code, Cursor, Gemini CLI, Codex CLI, Amp), CI/CD pipeline owners, and MCP gateway operators. Goal: make the first successful query fast, then standardise a repeatable loop with structured evidence falling out the other side.

Scope: MCP host setup (5 platforms), CI integration (5 platforms via `roam ci-setup`), gateway integration via the `McpDecisionReceipt` schema and HMAC-chained run ledger, and the OSCAL v1.2 control-mapping projection. Non-goal: hosted Roam deployment; private-deployment pilots are scoped separately by SOW.

Surface scale on v13.4: 267 commands, 243 MCP tools (15 in the default `core` preset, opt into `full` via `ROAM_MCP_PRESET`), 28 indexed languages. All local; no API keys.

## 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

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 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` / `would_deny_dry_run`), 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.