# MCP server and connectors directory > 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. Two pieces, built on that line: - **The evidence server**, inside the API at `${API_URL}/mcp`: an assistant (Claude, ChatGPT, Cursor, an agent framework) reads actions, verdicts, reasons and evidence pointers, contracts, coverage and usage; validates, dry-runs and drafts contracts without saving; and, with the `actions:record` scope, declares an action before it happens. - **The recorder**, `recorder/python` and `recorder/js`: a stdio proxy in front of any MCP server an agent uses, which records a mapped tool call as an action before forwarding it. See the READMEs there. Nothing on either surface writes a fact, saves or activates a contract, overrides a verdict, deletes anything, or reads a credential. No scope grants any of these. ## Transport and auth Streamable HTTP, stateless, JSON responses (`json_response=true`), mounted by `app/api/main.py` at the root so the OAuth metadata documents sit at the issuer. Bearer tokens of three kinds are accepted (`app/mcp/auth.py`): | Token | Who | Scopes | |---|---|---| | `spk_…` API key | A service, an agent runtime, a local MCP client | The key's scopes (Settings → API keys; keys from before scopes carry all) | | `cla_…` OAuth access token | A remote client a member approved on the consent page | The grant, capped to the member's current role on every call | | Session JWT | The web app itself | The member's role | Unauthenticated requests get `401` with `WWW-Authenticate: Bearer resource_metadata=…/.well-known/oauth-protected-resource/mcp`, which is how an OAuth-capable client discovers the authorization server. ## Scopes (`app/mcp/scopes.py`) `actions:read`, `actions:record`, `facts:write`, `contracts:read`, `contracts:validate`, `contracts:draft`, `reconcile:read`, `connectors:read`, `usage:read`. Presets: `recorder` (`actions:record`, `actions:read`), `evidence` (`facts:write`, `actions:read`, `connectors:read`, bound to named sources), `reader` (every read scope plus validate and draft), `full` (all). Owners, admins and analysts may hold every scope; viewers only the read scopes. A model-facing principal (an OAuth token, any bearer on this server) never holds `facts:write`: the model may declare its intent and read the verdict; the evidence arrives by another credential. Over REST an API key acts as an analyst when it may write and as a viewer otherwise, and each write endpoint checks its scope. ## Tools | Tool | Scope | What it returns | |---|---|---| | `get_action(action_ref)` | actions:read | The action with both lenses, status, reason codes, checks, evidence pointers | | `list_actions(contract_id?, workflow_id?, verdict?, period?, limit)` | actions:read | Actions with their latest verdict, newest first | | `pending_actions(limit)` | actions:read | Provisional actions, what they wait on, when they settle | | `workflow_summary(period?)` | actions:read | Per-contract counts for a month | | `record_action(contract_id, subject_id, …)` | actions:record | The provisional verification and the allowance; `channel: mcp` | | `verify_hash(hash)` | actions:read | Whether a statement / verdict / dispute hash exists and its chain holds | | `connector_health()` | connectors:read | Connections with status, trust, provides, last sync, watermark; never credentials | | `usage()` | usage:read | Plan, limits, features, usage, allowance | | `list_contracts()`, `get_contract(contract_id, version?)` | contracts:read | Summaries; YAML, compiled rules, plain language, versions | | `validate_contract(yaml)` | contracts:validate | Errors, compiled rules, plain language, weakening warnings | | `dry_run_verify(contract_id, period, yaml?, version?)` | contracts:validate | Counts per lens, verified amount, reasons; nothing persisted | | `draft_contract(action_type? \| contract_id?, …)` | contracts:draft | Proposed YAML with statistics and warnings; nothing saved | | `list_reconciliations(vendor?, period?, limit)`, `get_reconciliation(id)` | reconcile:read | Reconciliation views (coverage, claims, run, statement totals) | Resources: `commitlayer://reason-codes` (every code with label and explanation), `commitlayer://actions/{ref}`. Prompts: `investigate_failed_action(action_ref)`, `review_contract_change(contract_id, yaml)`. Every tool carries a title and the standard annotations (0.9.12). Fourteen are `readOnlyHint: true`, so a client such as Claude runs them without asking the person before each call; `record_action` is `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: false` (recording without an `action_id` twice is two actions). `openWorldHint` is false throughout. The hint must say what the scope enforces: `tests/test_mcp.py` fails when a tool's `readOnlyHint` disagrees with its `_call` scope, and the exported `product-catalog/mcp-tools.yaml` derives `read_only` and `destructive` from the annotations. Errors are returned as content, never as a stack trace: `{"error": {"code", "message", …}}` with codes `insufficient_scope` (plus `required_scope`), `plan_required` (plus `upgrade_to`), `not_found`, `invalid_request`, `invalid_contract` (plus `errors`), or an engine code. Every call is audited as `mcp.tool_called` with `object_id` = tool name, the actor (`apikey:`, ` via `, or the email) and `metadata {…args, ok, code}`. ## OAuth 2.1 (`app/mcp/auth.py`, `app/api/routers/oauth.py`) The API is the authorization server. Endpoints (served by the MCP SDK): `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource/mcp`, `POST /register` (dynamic client registration, open), `GET /authorize` (PKCE S256 required), `POST /token` (`authorization_code`, `refresh_token`), `POST /revoke`. Flow: the client registers → `/authorize` redirects the browser to `${WEB_URL}/oauth/consent?req=` → the signed-in member sees the client, the workspace and the requested scopes (`GET /v1/oauth/consent`), unticks what they do not want, approves or denies (`POST /v1/oauth/consent {req, approve, scopes?}`) → the answer carries `redirect_to` (the client's redirect URI with `code` and `state`, or `error=access_denied`) → the client exchanges the code with its verifier at `/token`. Codes are single use and live 10 minutes; access tokens 1 hour; refresh tokens 30 days. A refresh rotates the pair and the old pair dies. Tokens are stored hashed (`oauth_tokens`), bound to the member and the workspace they chose; a member who leaves the workspace loses every token, and a token never outranks the member's current role. Client secrets are stored envelope-encrypted because the token endpoint compares them in full. Audit: `oauth.approved {scopes, client_name}`, `oauth.denied`. ## The Claude connectors directory The server meets the directory's published requirements (checked against the live API on 2026-11-02): remote Streamable HTTP over HTTPS, a `401` with `resource_metadata` on unauthenticated calls, protected-resource metadata naming `/mcp` as the resource, authorization-server metadata with PKCE S256 and open dynamic client registration (a client that registers as a public client gets no secret and is accepted), authorization-code and refresh grants, per-tool errors as content, titles and annotations on every tool. Submission is at `claude.ai/directory/manage` (Submit new → MCP connector) from an account on a paid Claude plan. What the form asks for, and the answers: - **Connection**: `https://api.commitlayer.ai/mcp`, a single URL. - **Listing**. Name: *CommitLayer*. One-liner (≤200): *Read what your AI agents actually did: PASS, FAIL or UNKNOWN verdicts with the evidence, from the systems the action touched.* Description (≤2000): the first paragraph of `docs/mcp.md` in plain words: CommitLayer verifies agent actions against independent systems of record (Stripe, Shopify, CRMs, your own events) and returns a verdict with the step that did not land; through this connector Claude reads recorded actions and their verdicts, reasons and evidence pointers, lists what is still pending and what each is waiting on, reads contracts, validates and dry-runs contract changes without saving, drafts a contract from recorded actions, checks connector health and the workspace's plan and usage, and, when the token carries `actions:record`, records an action before it is performed. It never writes a fact, changes a verdict, activates a contract or deletes anything. Categories: Developer tools, Productivity. Documentation URL: `https://commitlayer.ai/mcp`. Privacy policy URL: `https://commitlayer.ai/legal/privacy`. Support: `support@commitlayer.ai`. Icon: `stateprf-ui/public/logo/icon-512.png`. Slug: `commitlayer` (permanent once published). - **Use cases**, three prompts that work on the demo workspace: *"Which of my agent's refunds failed this month, and why?"* (list_actions with verdict FAIL, then get_action); *"What is still waiting on a system of record, and when does it settle?"* (pending_actions); *"Draft an action contract from the refunds recorded in the last 30 days and tell me what limits it would set."* (draft_contract). Prerequisites: a CommitLayer workspace (free tier). The connector reads; it writes only through `record_action`, on a token that carries that scope. - **Authentication**: required; OAuth with dynamic client registration (`oauth_dcr`); the person signs in to CommitLayer and approves the client for one workspace with the scopes they choose. - **Data handling**: the API is our own; no health data, no sponsored content. - **Test & launch**: a reviewer account with sample data. Create a member of the synthetic demo workspace (181 verified refund-workflow actions, connectors, contracts) with a password sign-in, enter its email and password in the portal's test-account card, and write: *Add the URL as a custom connector, sign in with the credentials above when CommitLayer's consent page opens, approve the default scopes, then run `list_actions` with `verdict: FAIL`, `get_action` on one of the results, and `pending_actions`.* Confirm every tool was run through MCP Inspector or as a custom connector first. - **Compliance**: the seven acknowledgments; the server collects nothing from the conversation, stores no conversation content, and calls no API it does not own. A Community listing follows the automatic policy scan; a Verified one, where reviewers run every tool, is Anthropic's call later. Escalations: `mcp-review@anthropic.com`. ## Testing `tests/test_mcp.py` starts the API under uvicorn and drives it with the MCP Python client: tool catalog, every read tool, resources, audit rows, a read-only key refused `record_action` over MCP and `POST /v1/actions` over REST, a recorder key recording, a revoked key refused, metadata documents, and the full OAuth flow (registration, authorize, consent describe / deny / approve with trimmed scopes, wrong verifier, single-use code, refresh rotation, revocation).