Model Context Protocol

Give your agent an authorization path for contract changes

CodeRifts exposes exactly three tools via the Model Context Protocol — preflight_change_set, verify_receipt, and get_decision_details. Any MCP-compatible client — Claude Desktop, Cursor, Windsurf, or your own agent — can preflight a contract change set, verify a receipt, and look up a past decision. Additional governance operations are available over the separate REST API. Get started with Agent Quickstart Format coverage, read 2026-10-04, is the table on the documentation page. An incomplete analysis in authorize mode is ANALYSIS_FAILED and STOP, with the gap named.

What is the Model Context Protocol?

MCP is an open standard that lets AI agents discover and call tools from external services. Instead of hardcoding API calls, agents read a manifest file (mcp.json) that describes available tools, their input schemas, and endpoints. The agent then calls whichever tools it needs to complete a task. At runtime the authoritative discovery is the protocol’s own tools/list call against the server; mcp.json is a static advertisement clients use to find and configure the server, not the live tool list.

Five hint flips on one published server and one hint flip on a second, dated 2026-10-10 and re-derived from the app's fixtures on 2026-10-16, are on the annotation-flips page.

The drift digest dated 2026-10-10 is on the MCP drift digest.

Discover

Client finds the server via mcp.json, then calls tools/list for the live tools and their input schemas.

Call

Agent constructs a JSON request matching the tool's input_schema and sends it to the endpoint.

Act

Agent receives structured results and uses them to make decisions — block a deploy, warn a developer, or approve a merge.

Surface anchor

This page describes one snapshot of the MCP surface. These two values identify it, so a reader can tell whether the prose below still matches what the server serves.

server version
1.0.3
tools_sha256
sha256:cb989871bb8376655bff573cb074ecac1e367a2393a88aff067055c07722ecb6
verified
2026-09-14

Check it yourself in two commands — hash the tools the server returns, then compare against the digest we publish: the self-check on the verify page. It proves the tool text we serve is the tool text we published; it says nothing about whether a model read it or obeyed it.

Glama score badge for io.github.coderifts/api-governance

Measured 2026-10-05. Glama lists connector io.github.coderifts/api-governance as TDQS A (4.8/5.0, 3 tools, scored 2026-09-26 18:02) and Healthy, 99.5% uptime over 49 days. The transport line reads Streamable HTTP · MCP 2025-06-18. Last tested 2026-10-05 05:58. This is a third-party score of tool-definition quality and of availability. It does not say that anyone uses the server.

MCP Tools

Every tool is callable via any MCP-compatible client. Pass your API key as an Authorization: Bearer header.

Tool Input Output
preflight_change_set Use this when: a contract artifact (OpenAPI, GraphQL, protobuf, AsyncAPI, MCP manifests, or agent tool schemas) changes before merge, deploy, publish, or tool registration; AND any agent-executed operation with no supported contract type — send type agent_operation. Grant fields sit in one object, execution_grant_request {include_execution_grant, grant_version, tenant_id, executor_id, adapter_id, target_uri, expected_state_token, state_nonce, audience, policy_hash}; analyze ignores it; required is preflight_mode only. Mode-discriminated (Decision Spec v2): analyze → analysis_outcome, may_execute:false (no execution vocab); authorize → decision, execution_action, optional chain_receipt. See /decision-spec/
verify_receipt token valid is the signature. currently_authorized is whether this receipt authorizes this attempt. A valid signature with currently_authorized: false is not permission.
get_decision_details decision_id or fingerprint stored decision_result (verdict + receipt) + meta (source, created_at)

Only the three tools above are exposed through MCP. The endpoints below are REST integrations for callers without an MCP client — the agent-relevant surface, not the full product API.

Agent-relevant REST endpoints

Direct HTTP without an MCP client. This is the agent-relevant surface — not the full product API. Auth: Authorization: Bearer unless a route is documented as keyless.

Endpoint Description
POST /api/v1/diff Analyze an API contract change.
POST /api/v1/preflight Change-set preflight (same job as preflight_change_set). Requires preflight_mode; authorize may mint a receipt.
POST /api/v1/verify-receipt Verify a CodeRifts receipt.
POST /api/v1/decisions/lookup · GET /api/v1/decisions/:id Retrieve a previously issued decision with your key.
POST /api/v1/agent-readiness-score Score an API or manifest for agent readiness.
POST /api/v1/registry-validate Validate a set of specs together.
POST /api/v1/agent/preflight Evaluate changed agent tool schemas.
POST /api/v1/mcp-diff Compare two MCP manifests. A removed MCP resource, a resource template, a removed prompt, a prompt argument made required, or execution.taskSupport moving from optional to required is REQUIRE_APPROVAL with zero breaking changes, pattern MCP_SURFACE_NOT_ANALYZED. Diffing those surfaces is not built.

Test Your MCP Manifest

Paste your complete mcp.json URL. The result is the finding list. The score is a detail, not the decision.

A manifest is recognised as MCP by its schema_version or authentication field. Paste the whole document, not just the tool list a tools/list call returns — without one of those fields the manifest is read as an OpenAPI spec and scored against OpenAPI signals, which produces a number that does not describe your manifest. Measured 2026-09-14.

Plans & Limits

Measured in the server on 2026-09-30. A self-serve key is the free tier. There is no Team key, so this table has no unlimited request row.

Tier Requests / month Requests / minute Price
Free 1,000 requests 100 $0 — analyze, authorize public, verify; after the beta the planned Free boundary is a provider-verifiable public repository
Team no Team key 100 $149 / mo ($0 during public beta)
Enterprise not self-serve Custom from $1,500 / mo

Prices read from the live pricing page on 2026-09-20. No Pro tier is sold.

No Pro tier is sold. During the public beta every organization gets Team features at $0 with a self-serve key, public and private repositories alike, no separate Team key to request, and each key allows 1,000 requests a month: after that, /preflight authorize returns BETA_LIMIT_REACHED while its analysis keeps working; other API routes return 429. A self-serve key is 1,000 requests per month; above that, /preflight authorize returns BETA_LIMIT_REACHED while its analysis keeps working, and other API routes return 429. Any API key is limited to 100 requests per minute (API_KEY_MINUTE_LIMIT). The authorization-case counter is a label, and it is not the live 1,000-request cap. The keyless agent bucket, including POST /api/v1/preflight, answers x-ratelimit-limit: 60. Other keyless public calls are 30 per minute and 50 per day.

Quickstart

Add CodeRifts to your MCP client in under 60 seconds. Choose your client below.

Claude Desktop

Open Settings → Developer → Edit Config and add the CodeRifts server to your claude_desktop_config.json:

claude_desktop_config.json
{
  "mcpServers": {
    "coderifts": {
      "url": "https://app.coderifts.com/mcp",
      "headers": { "Authorization": "Bearer ${CODERIFTS_API_KEY}" }
    }
  }
}

Restart Claude Desktop. You will see CodeRifts tools in the tool picker.

Claude Code

Save this as .mcp.json in your repository root and commit it. Unlike a desktop user-config, Claude Code auto-loads it for everyone who works in the repo — and it loads the same way when Claude Code runs non-interactively in CI:

.mcp.json
{
  "mcpServers": {
    "coderifts": {
      "url": "https://app.coderifts.com/mcp",
      "headers": { "Authorization": "Bearer ${CODERIFTS_API_KEY}" }
    }
  }
}

Claude Code: claude mcp add --transport http coderifts https://app.coderifts.com/mcp. tools/list works without a key. Authorize needs one.

Gate contract changes in CI

Tools an agent can call are not a gate. Add a step that runs on contract changes and fails the job, so a risky change cannot pass whether the diff came from a human or from an agent:

.github/workflows/contract-gate.yml
- name: CodeRifts contract gate
  run: npx coderifts diff base.yaml head.yaml --ci --threshold 50

--ci exits non-zero once the risk score crosses --threshold, which fails the job. Full flag reference: CLI integration.

For the full governance decision — branch on execution_action (CONTINUE | CONTINUE_WITH_MONITORING | REQUEST_APPROVAL | STOP; unrecognised values fail closed) with a signed receipt — call the authorize preflight (the preflight_change_set MCP tool, or the Custom / curl tab). decision (ALLOW / WARN / REQUIRE_APPROVAL / BLOCK) is explanation, not the branch key. The threshold gate above is a risk cutoff, not that decision. See the Decision Spec.

Cursor

Open Settings → MCP and add a new server:

.cursor/mcp.json
{
  "mcpServers": {
    "coderifts": {
      "url": "https://app.coderifts.com/mcp",
      "headers": { "Authorization": "Bearer ${CODERIFTS_API_KEY}" }
    }
  }
}

Cursor will auto-discover all three MCP tools. Use them in chat with @coderifts.

Windsurf

Open Settings → Cascade → MCP and add:

~/.windsurf/mcp.json
{
  "mcpServers": {
    "coderifts": {
      "url": "https://app.coderifts.com/mcp",
      "headers": { "Authorization": "Bearer ${CODERIFTS_API_KEY}" }
    }
  }
}

Restart Windsurf. CodeRifts tools will appear in Cascade's tool list.

Custom Agent / curl

Fetch the manifest, then call any tool endpoint directly:

Step 1: Discover tools
curl -s https://coderifts.com/mcp.json | jq '.tools[].name'
Step 2: Call a tool
curl -X POST https://app.coderifts.com/api/v1/preflight \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "preflight_mode": "authorize",
    "context": { "operation": "merge" },
    "artifacts": [{
      "id": "api",
      "type": "openapi",
      "before": "openapi: 3.0.0\ninfo: {title: t, version: \"1.0.0\"}\npaths: {}\n",
      "after": "openapi: 3.0.0\ninfo: {title: t, version: \"1.0.1\"}\npaths: {}\n"
    }]
  }'
# Branch on execution_action when preflight_mode is authorize.
# Analyze (risk only): preflight_mode "analyze" → analysis_outcome + may_execute:false
# Full contract: https://coderifts.com/decision-spec/

Compatible Clients

CodeRifts works with any client that supports the Model Context Protocol.

💬

Claude Desktop

Anthropic's desktop client with native MCP support

Supported
⌨️

Cursor

AI-first code editor with MCP tool integration

Supported
🌊

Windsurf

Codeium's IDE with Cascade MCP support

Supported
🤖

Custom Agents

Any agent that reads mcp.json and calls HTTP endpoints

Supported

How It Works

The MCP integration adds a discovery layer on top of the existing CodeRifts API. No new infrastructure required.

1

Agent discovers tools

The agent fetches https://coderifts.com/mcp.json and reads the three MCP tools with their input schemas and endpoint URLs.

2

Agent calls a tool

The agent constructs a JSON payload matching the tool's input_schema and sends a POST request to the endpoint with your API key.

3

CodeRifts runs the analysis

The analysis runs and returns a decision, the patterns it named, and a fingerprint you can re-derive.

4

Agent receives structured results

The agent gets a JSON response with risk score, breaking changes, detected patterns, and mitigation templates. In analyze mode the body is informational only (analysis_outcome, may_execute: false) and cannot authorize execution. In authorize mode the agent branches on execution_action together with a verified, currently authorized receipt (operation, fingerprint and required context match) — merge, deploy and tool-call gates verify the same receipt independently.

Available now · npm @coderifts/sdk

Agent Governance SDK

A typed JavaScript/TypeScript SDK for programmatic access to every CodeRifts tool. Run preflight checks, explain decisions, and get unblock guidance — all from your agent code.

@coderifts/sdk
import { CodeRifts } from '@coderifts/sdk'

const cr = new CodeRifts({ apiKey: 'cr_live_...' })

// Branch on execution_action. risk_level is a label, not the decision.
const diff = await cr.diff({
  before: oldOpenApiYaml,
  after: newOpenApiYaml
})
if (diff.execution_action === 'STOP' || diff.execution_action === 'REQUEST_APPROVAL') {
}

Install now

npm install @coderifts/sdk pip3 install coderifts-sdk

Python and TypeScript SDKs are published and versioned. See the agent frameworks guide for full examples.

Get Your API Key

Three ways in. Connect to the MCP server with no key to list tools. Call authorize with a key when you need a receipt. Require the pull-request checks when a merge must stop. All three MCP tools are on every plan; paid plans add more repositories and higher monthly request limits.

Already have an API key? Jump to the quickstart above.