MCP verified-context quickstart

The connect.retrieve_verified MCP tool puts a Restormel Connect knowledge graph directly inside Claude Code, Claude Desktop, or Cursor. Every result the tool returns is an evidence-bound, citation-grounded claim — verified against its source, with the full provenance chain attached so both you and the AI can cite it accurately. This guide gets you from zero to a working tool call in under five minutes.

Prerequisites

• A Restormel Connect workspace with at least one ingested graph. If you have not built a graph yet, follow the Connect first graph onboarding guide first.
• A Gateway key (rk_…). Created in the Dashboard.
• Node.js ≥ 18 and either npm, pnpm, or the npx binary available in your shell.
• The Restormel CLI (for config generation):

  npm install -g @restormel/mcp @restormel/keys
  # or: pnpm add -g @restormel/mcp @restormel/keys

Step 1 — generate the config

Run this command in any directory. It prints the ready-to-paste mcpServers block for Claude Code, Claude Desktop, and Cursor with placeholder values you will fill in next:

keys init --mcp

To print only the config for one client, pass --mcp-client:

keys init --mcp --mcp-client claude-code
keys init --mcp --mcp-client claude-desktop
keys init --mcp --mcp-client cursor

Example output for Claude Code:

── Claude Code ──
Config file location:
  ~/.claude.json

Paste into mcpServers (merge with any existing servers):
{
  "mcpServers": {
    "restormel": {
      "command": "npx",
      "args": ["-y", "@restormel/mcp@latest"],
      "env": {
        "RESTORMEL_GATEWAY_KEY": "<your-gateway-key>",
        "RESTORMEL_CONNECT_API_BASE": "https://restormel.dev",
        "RESTORMEL_WORKSPACE_ID": "<your-workspace-id>"
      }
    }
  }
}

Step 2 — fill in your credentials

Replace the two placeholder values before pasting. Never commit a real Gateway key — inject it at runtime via your OS keychain, a password manager, or an environment file that is listed in .gitignore:

Step 3 — paste into your client's config file

Merge the mcpServers block into the config file for your client:

If the config file already has a mcpServers key, merge the restormel entry into the existing object — do not replace the whole file.

Step 4 — verify the tool is loaded

In your client, open the tools panel (or type a question to the agent) and confirm connect.retrieve_verified appears in the available tools list. For a quick smoke test:

# In the AI chat, type:
Use connect.retrieve_verified to find claims about [a topic in your graph]

The tool should respond with a structured list of verified claims, each carrying a citation and a trace_export_url. If the workspace has no ingested content yet, you will get an empty claims array — not an error. Ingest content first; see Connect first graph onboarding.

RESTORMEL_GATEWAY_KEY=rk_… RESTORMEL_CONNECT_API_BASE=https://restormel.dev \
  RESTORMEL_WORKSPACE_ID=<uuid> \
  npx -y @restormel/mcp@latest --check

Tool modes: strict and annotated

The connect.retrieve_verified tool has two modes that the calling agent can select per request:

You can instruct the agent to use a specific mode: "Use connect.retrieve_verified in annotated mode to show me all claims about X, including unverified ones."

How to cite correctly

The tool description instructs the calling agent to follow these rules automatically. For human review or when building integrations that post-process the results:

1. Quote verbatim from evidence[].quote. The quote is the exact span the Layer-1 binder confirmed is at the stated character offsets in the cited source version. Do not paraphrase it and present it as the verified text.
2. Attribute to citation (the source title): (Source: <citation>).
3. Include trace_export_url as the audit link: [trace](<trace_export_url>). This URL fetches the full provenance trace document (query, verification policy, every included and excluded claim with reasons) from GET /connect/v1/traces/{traceId}/export.
4. In annotated mode, never present inferred, unverified, contradicted, or excluded claims as confirmed facts. Label them appropriately (e.g. "reportedly", "unconfirmed", "disputed").

These rules are how the pipeline's guarantees carry through to the agent's output. See Verified context for the full guarantee chain.

Fresh-machine walkthrough

The following sequence covers setup on a machine with no prior Restormel install. Commands and expected output shapes are shown; a Gateway key and workspace ID are required for the live steps (marked with [key required]).

# 1. Install the CLI and MCP package.
npm install -g @restormel/mcp @restormel/keys
# Expected: no errors; both packages in node_modules

# 2. Generate the config (no credentials needed for this step).
keys init --mcp --mcp-client claude-code
# Expected output shape:
# ── Claude Code ──
# Config file location:
#   ~/.claude.json
# ...mcpServers block with placeholders...

# 3. Verify the MCP server binary is reachable.
npx -y @restormel/mcp@latest --check
# Expected: JSON manifest on stdout, exit 0
# { "version": "x.y.z", "tools": ["connect.retrieve_verified", ...] }

# 4. [key required] Smoke-test the server with real credentials.
RESTORMEL_GATEWAY_KEY=rk_live_…   RESTORMEL_CONNECT_API_BASE=https://restormel.dev   RESTORMEL_WORKSPACE_ID=<your-uuid>   npx -y @restormel/mcp@latest --check
# Expected: same JSON manifest, exit 0 — credentials are not validated at start
# (the server connects lazily on the first tool call)

# 5. Paste the filled-in config block into ~/.claude.json.
# Restart Claude Code.

# 6. In the Claude Code chat, verify the tool is listed:
# "What MCP tools do you have?"
# Expected: connect.retrieve_verified listed

# 7. [key required] Make a tool call:
# "Use connect.retrieve_verified to find supported claims about [topic]"
# Expected response shape:
# {
#   "ok": true,
#   "mode": "strict",
#   "claims": [ { "claim": { ... }, "state": "supported", "evidence": [...], ... } ],
#   "total_retrieved": N,
#   "total_after_mode_filter": M
# }

Troubleshooting

Related

• Verified context — what "supported" means, the five EBV states, the fail-safe gates, the G2 bar, and how to audit a claim yourself
• Connect first graph onboarding — build the knowledge graph this tool queries
• Context-regression CI — gate pull requests on graph quality with keys connect eval
• API reference — the OpenAPI spec for the Connect v1 endpoints the tool proxies
• Dashboard home — ingest setup, graph store, and quality reports for your workspace