MCP integration

Proofroom is MCP-native: agents record evidence through the Model Context Protocol with the same tool the company's own internal agents use.

Recording evidence is fire-and-forget. Every Proofroom call is asynchronous and non-blocking — it never blocks your agent. If Proofroom is unreachable, your agent continues exactly as if we did not exist. Evidence is a side-channel and never sits in your agent's critical path. Delivery gaps (receipts expected vs recorded) are visible via room_health.delivery and the public room page so missed evidence is detectable, not silent.

Descriptions are private by default. The public proof room renders only structural fields. Free-text titles and summaries appear publicly only if a human approves that specific text. Nothing an agent writes is published without human sign-off. The full record, including unpublished text, is hash-sealed at capture.

Materiality is classified server-side. Your agent does not need to reason about which actions are material: send events as work happens and Proofroom decides which ones mint receipts.

Endpoint

https://your-deployment/api/mcp

Add it to any MCP-capable client or agent framework as a remote MCP server. Bearer authentication is optional at the connector level:

Authorization: Bearer prf_live_...   (optional long-lived API key)

Zero-setup path (register, then record, same connection)

MCP hosts configure connector auth before tools run. You cannot usually paste the key register_agent returns into the connector mid-session. Use this path instead:

  1. Call register_agent (no API key required).
  2. On the same MCP connection, call record_evidence_event with:
    • use_case_slug = the returned proof_room_slug
    • api_key = the returned api_key
    • your event fields
  3. Give your human the claim_url and operator_instruction. Recording does not wait on the claim.

No dashboard step and no connector reconfiguration between register and record. For a long-lived connector later, set the bearer to that API key and omit api_key on each call.

Tools

register_agent

Registers a new agent without an API key. Creates an unclaimed draft Agent and Use Case passport and returns an API key, a proof room slug and a claim_url. A human must open the claim_url and complete the review gate (confirm the public description, set publication rules, confirm declared tools) before the room can be shared or a pack generated.

Arguments:

  • agent_name (string, required)
  • description (string, optional): private, owner-only until a human approves it at claim time
  • use_case_name (string, optional)
  • scope_summary (string, optional)
  • ref (string, optional): referral source, e.g. room_<slug> from a badge

Returns include api_key, proof_room_slug, claim_url, operator_instruction, proposed_scope, and next_step describing the immediate record_evidence_event call.

record_evidence_event

Records a hash-chained evidence event for a declared use case.

Arguments:

  • use_case_slug (string, required)
  • event_type (string, required): task_started, task_completed, decision_made, tool_called, data_accessed, external_message_sent, system_updated, output_generated, approval_requested, approval_completed, action_blocked, exception_raised, system_confirmed, agent_run_summary, playbook_activated, configuration_changed
  • event_summary (string, required): plain English, max 1000 characters
  • actor (string, optional)
  • system_reference (string, optional): e.g. github:pr:owner/repo#42
  • metadata (object, optional): payload-like keys are stripped. Optional config_components (flat name→hash map) seals configuration provenance. Prompt text is rejected; send a client-side SHA-256 digest instead.
  • occurred_at (ISO 8601, optional)
  • require_ack (boolean, optional, default false): opt-in durable acknowledgement. When true, the call returns only after the event is written and includes ack: { event_id, seq, event_hash }. When false, behaviour is unchanged: fire-and-forget for your task path. Proofroom never blocks your agent; if require_ack fails, your host agent decides whether to proceed.
  • api_key (string, optional): Proofroom API key from register_agent. Use this on the same MCP connection when the connector has no bearer (or a different key). When both connector bearer and api_key are present, api_key wins.

Auth: connector bearer or api_key argument. Without either, the tool returns Unauthorised.

Returns the chain sequence number, the event hash and any receipt minted. Material receipts are minted for external_message_sent, system_updated, approval_completed, action_blocked, exception_raised, system_confirmed, output_generated, decision_made, playbook_activated, configuration_changed, sensitive data_accessed, and undeclared tool_called. agent_run_summary stays on the chain but does not mint a receipt.

Critical actions (opt-in fail-closed)

You may designate event types or tool names as critical_actions on a use case. That list is shown on the proof room. For those actions, call record_evidence_event with require_ack: true and, if the call fails, do not proceed. Using require_ack makes your agent dependent on Proofroom availability for those actions only. The default remains fire-and-forget and its wording is unchanged.

get_trust_status

Returns the current verification status, decay state and chain integrity for a use case. Useful for agents that surface their own trust posture. Same auth as record_evidence_event (connector bearer or optional api_key).

Suggested playbook line for your agent

As you work, record evidence events through record_evidence_event. Recording is fire-and-forget: never wait on it, never retry it in your task path, and never block an action because recording failed.

Exception (opt-in only): for actions you designated as critical, call with require_ack true. If that call fails, do not proceed. That choice makes those actions dependent on Proofroom availability.

Receipts and independent checks

New material Action Receipts are Ed25519-signed. Offline verification does not need a call to the Proofroom API. See Signed receipts and /verify.

Chain heads are published to the public proofroom-anchors repository. Guide: External anchoring.