Guide: the Provenance MCP server

Add Provenance to Claude (or any MCP-capable agent) in about two minutes — no code. The @provenance/mcp-server package exposes Authorize and Attest as Model Context Protocol tools, so an agent can authorize actions, resolve step-up approvals, revoke intent, and check claim provenance conversationally.

This is the inverse of the framework adapters: those gate your tools with Authorize; this publishes our API as tools you can call.

The tools

| Tool | Does | Mutates? | | --- | --- | --- | | authorize_action | Mint an intent token for an action an agent is about to take | yes | | verify_intent | Verify a token before executing; may return an awaiting-approval result | yes | | check_approval_status | Look up a step-up approval by id | no | | revoke_intent | Revoke a token / session / device | yes | | get_policy | Read the active authorization (or claims_risk) policy | no | | simulate_policy | Evaluate facts against a policy without changing anything | no | | check_claim_provenance | Fetch an Attest claim's provenance + risk score | no | | verify_attestation | Verify a stored attestation by id | no | | get_usage | Read the account's metered usage + allowance | no | | trace_decision | Attribution trace for a traced inference (submits a metered job, waits, returns the signed manifest) | yes |

Each tool is a thin wrapper over one @provenance/sdk call. Scope and plan limits stay server-side — a tool can only do what the API key it runs under can already do. The server holds no secret beyond that key.

Pending approvals never hang

When a policy requires human step-up approval, verify_intent returns a structured "awaiting human approval (id …, expires …)" result instead of blocking past the client's timeout. The agent surfaces it, and either polls check_approval_status or re-runs verify_intent once the human approves.

Connect over stdio (local, npx)

Add this to your Claude Desktop / Claude Code MCP config (see examples/claude-config.json):

{
  "mcpServers": {
    "provenance": {
      "command": "npx",
      "args": ["-y", "@provenance/mcp-server"],
      "env": {
        "PROVENANCE_API_KEY": "prv_test_…",
        "PROVENANCE_BASE_URL": "https://api.provenance.example"
      }
    }
  }
}

PROVENANCE_API_KEY is required; PROVENANCE_BASE_URL overrides the default hosted API (point it at your local sandbox for testing). The key travels only in the environment — never on the command line, where it would leak into ps.

Connect over HTTP (hosted, no install)

The API also mounts the MCP Streamable-HTTP transport at POST /v1/mcp. Point an HTTP-capable MCP client there and authenticate with your API key:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://api.provenance.example/v1/mcp"),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.PRV_KEY}` } } },
);
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();          // the ten tools above
await client.callTool({ name: "get_usage", arguments: {} });

A hosted tool call is just an API call: it runs through the same rate limits, scope checks, plan gates, and usage metering as a direct HTTP request — nothing is bypassed.

Try it

> Authorize a $500 wire to Acme, then verify it.

Claude calls authorize_action then verify_intent; if your policy needs approval you'll get an approval id to resolve. Read-only questions ("what's my usage?", "show the provenance for claim CLM-123") work the same way.