MCP · CommitLayer

MCP

CommitLayer over the Model Context Protocol.

Connect an assistant to the evidence, and put a recorder in front of the tools an agent uses. The assistant reads verdicts and reasons; the agent declares what it is about to do; the verdict still comes from your systems of record.

The agent may declare its intent. It may read the verdict. It must never control the independent facts, the governing contract, or the final evidence.

Start free API quickstart

The evidence server

One server, inside the API, at https://api.commitlayer.ai/mcp. Streamable HTTP, stateless, JSON responses. The same tools for every client; the plan is checked at call time and answers with the plan that unlocks a tool rather than hiding it.

Actions and verdicts

get_action	One recorded action with both lenses, status, reason codes, the checks that ran and evidence pointers.
list_actions	Recorded actions by contract, workflow, verdict or month, each with its latest verdict.
pending_actions	Actions whose verdict is still provisional, with the sources they wait on and when they settle.
workflow_summary	Per-contract counts for a month: pass, fail, unknown, pending, compensated.
record_action	Declare an action before it is performed. Returns the provisional policy verdict. Needs the actions:record scope.

Contracts

list_contracts / get_contract	The workspace's contracts and the library's: YAML, compiled rules, plain language, versions.
validate_contract	Schema errors, compiled rules, plain-language rendering and weakening warnings. Nothing is saved.
dry_run_verify	What a contract (saved or proposed) would decide over a month's claims and facts. Nothing is persisted.
draft_contract	A contract proposed from the actions already recorded and the effects observed around them. Nothing is saved.

Evidence, coverage and usage

verify_hash	Whether a statement, verdict or dispute package with a given hash exists and whether its chain is intact.
connector_health	Every connection: status, trust level, what it provides, last sync and watermark. Never credentials.
list_reconciliations / get_reconciliation	A vendor's claims for a period: coverage, claims, run and statement totals.
usage	Plan, limits, usage this month and the allowance of verified actions.

Two resources, commitlayer://reason-codes (every reason code with its plain-English meaning) and commitlayer://actions/{id}, and two prompts, investigate_failed_action and review_contract_change, that walk an assistant from a verdict to the evidence without letting it invent any. Every call is written to the workspace audit log with the principal that made it.

Connect a client

With an API key: Claude Code, Claude Desktop, Cursor, your own agent

Create a key under Settings → API keys with the Read-only preset and send it as the bearer token. Any client that speaks MCP over streamable HTTP works the same way.

claude mcp add --transport http commitlayer https://api.commitlayer.ai/mcp \
  --header "Authorization: Bearer spk_..."

{
  "mcpServers": {
    "commitlayer": {
      "type": "http",
      "url": "https://api.commitlayer.ai/mcp",
      "headers": {"Authorization": "Bearer spk_..."}
    }
  }
}

With OAuth: Claude.ai, ChatGPT and other remote clients

Add https://api.commitlayer.ai/mcp as a connector (in Claude.ai: Settings, Connectors, Add custom connector). The client registers itself, sends you to CommitLayer to sign in and approve it for one workspace with the scopes you choose, and receives a token bound to that workspace and to you. Tokens expire after an hour and refresh for thirty days; leaving the workspace ends them; a viewer's token can never record. The authorization server is the API itself: metadata at https://api.commitlayer.ai/.well-known/oauth-authorization-server, PKCE required, dynamic registration open.

The recorder

A stdio proxy you put in front of any MCP server an agent uses. It forwards every message unchanged and, when the agent calls a mapped tool, records the intent as an action before the call goes through. The tool's own answer is never sent: a tool saying “refund issued” is a claim, not evidence.

pip install commitlayer-mcp-recorder      # or: npm i -g @commitlayer/mcp-recorder
export COMMITLAYER_API_KEY=spk_...       # a Runtime recorder key
commitlayer-mcp-recorder --map stripe.json -- npx -y @stripe/mcp --tools=all

{
  "agent_id": "support-bot",
  "tools": {
    "refund_payment": {
      "contract_id": "refund_workflow",
      "action_type": "refund_order",
      "subject": "arguments.order_id",
      "params": {"amount": "arguments.amount", "currency": "arguments.currency"},
      "action_id": "refund:{arguments.order_id}"
    }
  }
}

The mapping names the contract each tool falls under and where in the call its subject and parameters are. Unmapped tools pass through untouched. If CommitLayer cannot be reached the call still goes through and a warning is logged (fail-open; --no-fail-open refuses it instead). What the recorder sends is the agent's own declaration, so the action carries the self-reported trust level; the verdict is decided by what your systems of record show afterwards, as for any other action. Python and TypeScript, standard library only, in the recorder/ directory of the API repository.

What it never does

Write, edit or delete a fact. Facts come from read-only connectors, the facts API or OpenTelemetry, under credentials the model never sees.
Save, select or activate a contract. Validate, dry-run and draft return text; a person saves it in the app, where the weakening check applies.
Override, re-issue or delete a verdict. Verdicts are hash-chained; the chain is never rewritten.
Read a credential, a member list or a billing detail. Connector health reports status and watermarks only.

No scope grants any of these, and none will be added. A model-facing principal, whether a key or a person's OAuth token, can declare and read. Changing what counts as evidence stays with people, in the app, where it is audited and alerted.

Keys and scopes

Runtime recorder	actions:record and actions:read only. The agent's side: for the recorder and the SDK decorator. Cannot push facts.
Evidence	facts:write, actions:read, connectors:read, bound to named sources. The pipeline's side: pushes facts and watermarks. Cannot record actions.
Read-only	Read actions, verdicts, contracts, coverage and usage; validate, dry-run and draft. For an assistant. Acts as a viewer over REST.
Full access	Every scope, both sides of the line. For a backend you control end to end; prefer the split presets.

Scopes are per key and per OAuth grant: actions:read, actions:record, contracts:read, contracts:validate, contracts:draft, reconcile:read, connectors:read, usage:read. Available on every plan; an action recorded over MCP counts toward the monthly allowance like any other.

Start free Ask a question