Connect Roam to your workflow

MCP host integration

Preview a maintained client template with roam mcp-setup. Add --write to install it after reviewing the path and settings. The generator configures a server process; it does not inspect the connected client's tool inventory. Restart the connection after changing its configuration or preset, then try a query in the client. See configuration and tool discovery for the distinction.

Generator targets in this checkout: 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 --write
# Alternatively: claude mcp add roam-code -- roam mcp

2. Verify tool visibility

Restart the connection and inspect Roam's tools in Claude Code. roam mcp --list-tools-json is a separate local inventory, not proof of what the connected client exposes.

3. First end-to-end workflow

Ask the agent to find one function in your project and inspect its callers. Use the core-preset example for actual MCP call names and arguments, then follow the connection and routine checklist.

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. Try a repository question

Restart the connection, check its tool list, and ask the agent to locate a function you know. Compare the returned file and line with the source. Continue with the connection checklist.

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. Check the active connection

Restart the connection and use the same first-query check. A successful configuration write alone does not prove that Gemini loaded the server.

Codex CLI

1. Configure via command or config file

codex mcp add roam-code -- roam mcp
codex mcp list

2. Alternative configuration route

Alternatively, run roam mcp-setup codex-cli --write to safely merge the emitted TOML into ~/.codex/config.toml.

3. Inspect the active server

codex mcp list lists configured servers; use /mcp in the Codex CLI session to inspect active servers, then make a real query. If needed, set the server's cwd to the intended project and use an absolute executable path. See OpenAI's MCP configuration guide.

Finish with the connection and routine checklist.

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 the connection

Reload the server in Amp and run the first-query check. The JSON above describes the server entry; follow your installed client's settings format when adding it.

VS Code

roam mcp-setup vscode
roam mcp-setup vscode --write

The generator targets the project's .vscode/mcp.json. Review the preview first, restart the MCP connection, and check Roam's tools in the agent interface. Finish with the connection and routine checklist.

Windsurf

roam mcp-setup windsurf
roam mcp-setup windsurf --write

The generator targets the user-level ~/.codeium/windsurf/mcp_config.json. Confirm the intended project root after restarting the connection, then follow the connection and routine checklist.

Check the connection, then add the routine

• Confirm the connected client exposes the intended Roam preset and uses the intended project root.
• Ask the agent to locate a known function using roam_search_symbol, then inspect its references with roam_uses. Check the returned source locations.
• Inspect result status, scanned scope, freshness, and any partial or failed checks. Follow result-state guidance; an empty list alone is unknown.

Connection makes tools available; it does not ensure the agent uses them. Add a small instruction to your project's agent guidance:

Use Roam to find relevant code and inspect indexed callers before a non-trivial edit.
Read the returned source locations and limitations. After editing, refresh the index
and run the project's required tests and review checks. Keep missing evidence explicit.

CI/CD pipeline integration

Generate a starting pipeline for your CI platform. Inspect its checks, triggers, permissions, and package pins before committing it; comment and artifact behavior differ by platform. A generated workflow is configuration, not evidence that its checks have run successfully.

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 its configured trigger — an opt-in cosign/keyless signing path using OIDC, Fulcio, and Rekor. This is not automatic SLSA qualification; inspect the resulting statement and verify its signer and subject. Keyless signing uses the network. 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; a gateway can add network policy, semantic inspection, and audit aggregation beyond Roam's bounded producer-side checks. 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 -m roam.evidence.mcp_receipt_schema --out mcp-receipt.schema.json

Use the Python environment containing your Roam installation. This module ships in the package; a Roam source checkout is not required.

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. These receipt fields are digests, not raw payloads; response handles and other saved artifacts can still contain analysis data. Recorded actor labels are not authenticated identity.

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 --json runs verify <run_id>
roam --json runs verify --all   # every run in this repo

Choose one form. Substitute the actual run ID in the first; the second inspects all available runs, not just the intended change.

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 .roam/oscal/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.

See also

• Command reference: Examples and command index — worked examples, global output options and the complete command index. For a command's own flags, run roam <command> --help.
• MCP security stance: Inside-server vs gateway — what Roam owns and what your MCP host owns.
• Configuration and discovery: Preview the client configuration — what the generator checks and what needs a connected-client test.
• 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.
• Try your own history: use the free local sample over HEAD~5..HEAD, or request a paid report for an agreed PR scope and founder walk-through. The conditional 50% Review credit follows the launch-based terms.