Integrations: MCP, Claude Agent SDK and HTTP
Cerata is one HTTP call, so it fits any stack. For agent frameworks there are ready paths: a hosted MCP server, a hook that gates Claude Agent SDK tool calls, and a gateway that sits in front of your own MCP tools.
Hosted MCP server
Cerata runs an MCP server at https://clearance-kohl.vercel.app/mcp over Streamable HTTP. Authenticate with your API key as a Bearer token. It is stateless: no sessions and no event stream, so GET answers 405. Any MCP client that speaks Streamable HTTP can connect. See the glossary if MCP is new to you.
claude mcp add --transport http cerata https://clearance-kohl.vercel.app/mcp \
--header "Authorization: Bearer $CERATA_API_KEY"
{
"mcpServers": {
"cerata": {
"type": "http",
"url": "https://clearance-kohl.vercel.app/mcp",
"headers": {
"Authorization": "Bearer ${CERATA_API_KEY}"
}
}
}
}
Tools it offers:
| Tool | What it does |
|---|---|
preflight | Decide one action, exactly as POST /v1/preflight. Takes an optional idempotency_key. |
get_hold_status | A held check's status, as GET /v1/holds/{id}. |
verify | Verify a receipt or token; consume: true redeems a token once. |
ask_coverage | Ask what Cerata covers, with cited passages, or no_coverage. |
explain_rule | One rule with its citations, by a rule id from rules[].id. |
approve_campaign | Check a campaign with per-recipient results and one signed campaign receipt. |
Connecting MCP gives your model a tool; it doesn't force a check. Tell the agent to call preflight before every outbound action and to act only on clear. To enforce it in code, use the hook or the gateway below.
Claude Agent SDK hook
A PreToolUse hook runs before a tool call and can deny it. Map the tool's input to the facts of the action it would take; the hook calls Cerata and lets the tool run only on clear. Return undefined from map for a call that takes no outbound action, and it runs untouched.
The TypeScript SDK is in private preview; ask us for access. Everything it does is a plain HTTPS call, so the HTTP examples work today from any language.
import { query } from '@anthropic-ai/claude-agent-sdk';
import { createClient } from '@cerata/sdk';
import { claudeAgentSdkPreToolUse } from '@cerata/sdk/guards';
const cerata = createClient({ apiKey: process.env.CERATA_API_KEY!, baseUrl: 'https://clearance-kohl.vercel.app' });
// Runs before every call to the place_call tool. Only a clear lets it through.
const checkCalls = claudeAgentSdkPreToolUse({
client: cerata,
matcher: 'place_call',
map: (input: { phone: string; at?: string; address?: { line1: string; city: string; state: string; zip: string } }) => ({
action: { type: 'outbound_call', purpose: 'telemarketing', at: input.at ?? new Date().toISOString() },
sender: { name: 'Gulf Coast Motors' },
recipient: { phone: input.phone, ...(input.address && { address: input.address }) },
}),
});
for await (const message of query({
prompt: 'Call the lead at +1 813 555 0142 about a test drive',
options: { hooks: { PreToolUse: [checkCalls] } },
})) {
// ...
}
// The same hook with no SDK: a plain PreToolUse callback over HTTP.
const checkCalls = {
matcher: 'place_call',
hooks: [async (input: { hook_event_name: string; tool_input: any }) => {
if (input.hook_event_name !== 'PreToolUse') return {};
const deny = (reason: string) => ({
hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason },
});
try {
const res = await fetch('https://clearance-kohl.vercel.app/v1/preflight', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.CERATA_API_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
action: { type: 'outbound_call', purpose: 'telemarketing', at: new Date().toISOString() },
sender: { name: 'Gulf Coast Motors' },
recipient: { phone: input.tool_input.phone },
}),
});
const check = await res.json();
if (check.decision === 'clear') return {}; // carry on; normal permissions apply
return deny(`Cerata ${check.decision}: ${(check.reasons ?? []).join(', ')}`);
} catch (e) {
return deny('Cerata check failed, so the call is not allowed'); // fail closed
}
}],
};
How the SDK hook behaves:
- Flag, hold, block and any failed check all deny the tool call. The reason, including the receipt id, goes back to the model so it can revise.
- On clear it answers
allow, which also skips the permission prompt for that one call. - If the check returned a token, it adds
clearance_tokento the tool input. Make sure the tool's schema accepts that extra field.
The same package has guards for other frameworks: an AI SDK tool approval function, an OpenAI Agents SDK tool input guardrail, and a wrapper for any async function. All fail closed.
MCP gateway
Already serve your tools over MCP? The gateway sits in front of your MCP server. For each tool you map, it runs a check before the call; a call that isn't cleared never reaches your server and returns an MCP tool error with the reason. Unmapped tools pass straight through. Like the hook, it adds clearance_token to the arguments when a token was returned. It is in private preview alongside the SDK.
import { createGateway } from '@cerata/mcp-gateway';
import { createClient } from '@cerata/sdk';
const gateway = createGateway({
upstream, // an MCP Client connected to your real tool server
client: createClient({ apiKey: process.env.CERATA_API_KEY!, baseUrl: 'https://clearance-kohl.vercel.app' }),
map: {
send_sms: (args) => ({
action: { type: 'outbound_text', purpose: 'telemarketing', at: new Date().toISOString() },
sender: { name: 'Gulf Coast Motors' },
recipient: { phone: String(args.to) },
content: { text: String(args.body) },
}),
},
});
// Serve it from your own MCP server:
server.setRequestHandler(ListToolsRequestSchema, () => gateway.listTools());
server.setRequestHandler(CallToolRequestSchema, (req) => gateway.callTool(req.params.name, req.params.arguments ?? {}));
HTTP from any platform
No SDK needed. Workflow tools, Python agents, serverless functions and no-code platforms can all call POST https://clearance-kohl.vercel.app/v1/preflight with a Bearer key and JSON body. Put the call in the step right before the action, and branch on decision: only clear continues. The API reference has curl, TypeScript and Python for every endpoint.
- Send an
Idempotency-Keyso platform retries don't double-check. - Set a timeout, and treat a timeout as “don't act”.
- Store
receipt_idnext to the action in your own records.
Receivers: require a check
The service that actually sends, such as a dialer, SMS gateway or listing feed, can refuse anything Cerata hasn't cleared. The agent asks for a token with token.aud set to the receiver, then sends the same facts with the token in the clearance-token header. The receiver checks the token is genuine, unexpired, meant for it and bound to exactly those facts, and can redeem it once.
import hashlib, json
import requests
def receive_call(facts: dict, token: str | None):
"""A dialer that refuses any call Cerata hasn't cleared for exactly these facts."""
if not token:
return 403, {"error": {"code": "clearance_required"}}
action = {"type": facts["action"]["type"], **facts} # the action core
res = requests.post(
"https://clearance-kohl.vercel.app/v1/verify?consume=true",
json={"token": token, "aud": "dialer.example.com", "action": action},
timeout=5,
)
if res.status_code >= 500:
return 503, {"error": {"code": "issuer_unavailable"}} # fail closed
out = res.json()
if not (out.get("valid") and out.get("consumed")):
code = "token_replayed" if out.get("reason") == "already_consumed" else "token_invalid"
return (409 if code == "token_replayed" else 403), {"error": {"code": code, "reason": out.get("reason")}}
return 200, dial(facts)
This sample assumes the body holds only documented preflight fields, exactly as they were checked.
Receivers answer refusals as {"error": {"code", "reason"}}:
| code | Status | Meaning |
|---|---|---|
clearance_required | 403 | No token was presented. |
invalid_request | 400 | The body isn't JSON or has no action to bind the token to. |
action_mismatch | 403 | The token was issued for different facts. |
audience_mismatch | 403 | The token was issued for another receiver. |
token_expired | 403 | Outside the token's time window. |
token_invalid | 403 | Bad signature, key or format. |
token_replayed | 409 | The token was already redeemed. |
issuer_unavailable | 503 | Cerata couldn't be reached, so the receiver fails closed. |
A receiver library for TypeScript (Fetch API, Hono and Express middleware) that verifies tokens offline before redeeming them is in private preview. The protocol is part of the open receipt/v1 format.
General information, not legal advice. Cerata is not a law firm. A check tells you what the rules Cerata covers say about one action; it is not a guarantee that the action is lawful.