#Ratifia MCP (for agents)
Give an AI agent a human-in-the-loop. The Ratifia MCP server lets an agent (Claude Code, Claude Desktop, Cursor, or anything that speaks MCP) pause on a human decision mid-task and resume once it's answered. The agent is the "engine"; Ratifia owns the decision, the notification, and the verdict.
Use it when the agent is about to do something consequential (deploy, delete, spend, send an email externally), needs a human to pick between options, or wants a person to review and refine a draft before it goes out.
#Add Ratifia to Claude or ChatGPT
No install, no API key: Ratifia is also hosted, so any AI app that takes an MCP server URL can connect and sign you in.
| Server URL | https://mcp.ratifia.com/mcp |
| Sign-in | OAuth with your Ratifia account. If you belong to several organizations, you pick one. |
- Claude (claude.ai, Desktop, mobile): Settings → Connectors → Add custom connector, paste the URL, then Connect and sign in.
- ChatGPT: Settings → Apps & Connectors → Create (developer mode), paste the URL, choose OAuth, and sign in.
Then ask, for example: "Before you send this, ask me in Ratifia." The decision lands in your Ratifia inbox, addressed to you unless the request names other approvers or a policy.
What a connected app can do is fixed: it acts as you, but only within what an integration key can do. It can ask for, wait on and cancel decisions, and read policies. It can never approve a decision or change who approves, even if your own role can. If your role can't ask for decisions, neither can the app.
Every connection shows under API Keys → Connected apps, where you can revoke it; the app is cut off on its next request. Admins see and can revoke everyone's.
The same URL also accepts an org API key (Authorization: Bearer fp_live_…), for clients that send a fixed header, such as Claude Code or the Claude API's MCP connector. With a key there is no signed-in person, so each request must name approvers or a policy.
A hosted await_decision waits at most 55 seconds per call (default 45), since hosted apps give up on a tool call sooner than a local one. If it comes back pending, the app just calls it again.
#Quick start
Fastest path: let your AI assistant wire it up. Copy the block below and paste it to your coding agent: Claude Code, Cursor, Claude Desktop, Windsurf, or any MCP client. It carries everything the assistant needs; it will ask you for your API key rather than guess it.
Install the Ratifia MCP server into my MCP client. Ratifia is a human-in-the-loop MCP: it lets you (the agent) pause on a humandecision mid-task and resume once it's answered. Add it as a stdio server. Server to add: name: ratifia command: npx args: ["-y", "@ratifia/mcp"] env: RATIFIA_API_KEY (required): my org-scoped worker API key RATIFIA_APPROVER_EMAIL (optional): who approves, one email or a comma-separated list Steps:1. Ask me for RATIFIA_API_KEY and RATIFIA_APPROVER_EMAIL. Never invent them. (I get the key from the Ratifia dashboard -> API Keys; it's shown once at creation.)2. Detect my client and edit the RIGHT config: - Claude Code -> run: claude mcp add ratifia -e RATIFIA_API_KEY=<key> \ -e RATIFIA_APPROVER_EMAIL=<email> -- npx -y @ratifia/mcp - Claude Desktop -> edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json), add the server under "mcpServers". - Cursor -> edit ~/.cursor/mcp.json (or .cursor/mcp.json in-project), under "mcpServers". - Other client -> add the equivalent stdio server entry.3. Use ONLY the fields above. Add no other env vars.4. Tell me to restart the client, then confirm these tools are available: request_decision, await_decision, check_decision, list_pending_decisions, cancel_decision. If anything is unclear, ask me instead of guessing.
Prefer to do it by hand? The full config and options are in Configure it below.
#Configure it
The MCP runs as a local process your client launches over stdio. Add it to your MCP client's config with one required env var, your Ratifia API key:
{ "mcpServers": { "ratifia": { "command": "npx", "args": ["-y", "@ratifia/mcp"], "env": { "RATIFIA_API_KEY": "your-org-worker-api-key", "RATIFIA_APPROVER_EMAIL": "you@example.com" } } }}
That's it. Restart your client and the agent gains the Ratifia tools.
Where the API key comes from
RATIFIA_API_KEY is an org-scoped worker API key. Create one in the Ratifia dashboard under API Keys. It's shown once at creation (store it somewhere safe; it's hashed afterward and can't be retrieved). It scopes every decision the agent opens to your org.
#Environment variables
| Variable | Required | Default | Purpose |
|---|---|---|---|
RATIFIA_API_KEY | ✅ | none | Org-scoped worker API key (from the dashboard). |
RATIFIA_API_URL | https://api.ratifia.com | API base; point at a different environment. | |
RATIFIA_APP_URL | https://app.ratifia.com | Dashboard base for the decision links returned to the agent. | |
RATIFIA_APPROVER_EMAIL | none | Without a policy: who can answer, as one email or a comma-separated list (sent as approvers). Ignored when RATIFIA_POLICY is set: the policy decides who. | |
RATIFIA_POLICY | none | The key of a policy deciding who reviews the agent's decisions, the quorum they need, and the expiry (a timeout_minutes from the agent is then not sent). It must exist: an unknown key is a tool error, and the gate hook denies. | |
RATIFIA_WORKFLOW | ratifia-mcp (ratifia-gate for the hook) | The workflow decisions are filed under: the project or effort the dashboard's Workflow filter groups by. A request_decision call can override it with workflow. (0.9.0+) |
Who is asked, and on which surface, is decided inside Ratifia by the org's policy; see how the approver is reached. The MCP is a thin request/verdict bridge.
#Multiple environments
Point separate registrations at different environments by giving each its own URL + key, e.g. a ratifia-stg and a ratifia-prod, each with its own RATIFIA_API_URL and RATIFIA_API_KEY.
#The tools
| Tool | What it does |
|---|---|
request_decision | Open a decision, notify the human, return a decision_id. Name who answers with approvers (emails) or policy (a policy key); otherwise the server's default applies. |
await_decision | Block until the verdict lands or max_wait_seconds elapses (default 90, max 110; hosted: default 45, max 55). If it returns status: pending with timed_out: true, call it again to keep waiting. |
check_decision | Poll a decision's status once. |
list_pending_decisions | The agent's inbox: what's outstanding. |
cancel_decision | Withdraw a decision the agent no longer needs. |
attach_evidence | Attach material the decision is judged on (a Slack thread, an email) while it's pending. |
await_decision and check_decision also return policy_version and policy_version_id: the version of the policy the decision was created under, or null when none applied.
#Filing decisions: workflow and step
Every decision carries two labels, and the dashboard's Workflow filter groups by the first:
workflow: the project or ongoing effort, e.g. the repo name orbilling-refunds. Reuse the exact same string for related decisions, and keep ids, versions and environments out of it.step: what's specific to this decision, e.g.deploy-v2.3-prodorrefund-INV-1042. Defaults to the title.
Without them every agent decision lands in one ratifia-mcp group. Set a default per server with RATIFIA_WORKFLOW, or pass workflow / step to request_decision (0.9.0+).
request_decision also takes:
tool_name/tool_args: shown under What you're approving as a Tool call panel of exactly what would run.risk(0.14.0+):severity(low,medium,high),reversible,impact({ label, value, normal? }lines with real numbers) andif_wrong. These fill the decision page's How hard to look, What changes and If it's wrong sections. Leave it out and those sections show as Not stated. Every value is tagged as the agent's own claim, and a policy can raise the severity but never lower it.links(0.14.0+):{ label, url, description? }, http(s) only, for the PR, ticket or record the decision is about. These are the reviewer's clickable links: a URL written insidecontextshows as plain text.evidence: the same itemsattach_evidenceaccepts.
Typical loop: the agent calls request_decision before the risky step, waits for the verdict, and proceeds only on approved. On rejected/expired it adapts.
How it waits matters. await_decision blocks the turn, which is right for a long-running agent and wrong for one that runs in short cycles — a cycle that ends while a decision is open will never see the verdict unless something reads it back. See FAQ: my agent never came back for the verdict.
#Decision shapes
request_decision isn't only yes/no. Shape the answer with response_type:
response_type | The human… | The agent reads |
|---|---|---|
approval (default) | approves or rejects | verdict (+ note) |
select | picks from options you supply (set allow_multiple for many) | response_value.selected (ids → labels via response_spec.options) |
text | types a value | response_value.text |
request_decision( title: "Which environment?", question: "Where should I deploy?", response_type: "select", options: [{ label: "Staging" }, { label: "Production" }])
#Refining a draft: Conversational Approvals
Pass proposed_output to attach an editable draft (e.g. an email). The human refines it in conversation in the Ratifia app, and the agent gets their final version back on output.content (with a refined flag). Act on output.content, not the draft you sent. See Conversational Approvals.
request_decision( title: "Send welcome email", question: "Review this before I send it.", proposed_output: { title: "Welcome email", content: "<your draft>" })
#Teach your agent when to ask: a skill template
The MCP gives an agent the tools. A skill tells it when to reach for them, what to put in the ask, and how to file it, so decisions arrive in a shape a person can actually act on instead of whenever the model happens to think of it. For Claude Code, save this as .claude/skills/ratifia-decision/SKILL.md in a repo (shared with the team) or ~/.claude/skills/ratifia-decision/SKILL.md (just you), then adjust the lists to your own risk lines.
Why the template is shaped this way
It borrows the ordering of I-PASS, the clinical handoff protocol — severity first, then detail, then contingency — which cut medical errors 23% across nine hospitals without making handoffs take longer. Structure is free; attention isn't. So the template always imposes the shape, and spends real friction (a forced choice, a read-back) only where the blast radius earns it.
---name: ratifia-decisiondescription: Ask a human for a decision via Ratifia before a consequential or irreversible action, or when a requirement is ambiguous and guessing wrong is costly — and write the ask so they can actually decide. Use before production deploys, deletes/drops, data migrations, spending, sending anything externally, or credential changes. Requires the Ratifia MCP tools (request_decision, await_decision).--- # Asking a human via Ratifia You are briefing someone who was not there while you worked, who has seconds ofattention, and who cannot re-derive what you know. A decision is a **handoff**: thequality of your write-up is the quality of their decision. ## When to ask Ask before:- Production deploys, deletes/drops, data migrations- Spending money, or sending email/messages to people outside the team- Rotating or changing credentials- A real fork where the person's preference changes the outcome Don't ask for trivial, reversible or already-authorized steps. And don't ask when youwould proceed regardless of the answer — an ask you ignore teaches them to approvewithout reading, and the next ask, the one that matters, gets the same glance. Keep asks rare and well-scoped. One decision per judgment call, carrying everythingneeded to answer it, beats three thin ones. ## Write the ask in this order 1. **Scale and reversibility, first.** Put the number in the `title` so they calibrate before they read: "Drop legacy_orders (1.2M rows, irreversible)", not "Schema cleanup". Count things: "deletes 1,240 of 1,300 rows across 3 tables", "emails 847 customers". Concrete counts, never a risk label or a confidence score.2. **Where you are.** One or two lines: what you were asked to do, what you've done, and why this step is now in front of them.3. **Exactly what runs.** Pass `tool_name` and `tool_args` so they see the real call in a Tool call panel instead of your prose about it. Pass `risk` with the same numbers, so the page shows severity, impact and what happens if it's wrong in their own sections, and `links` for anything they should open.4. **What you verified, and what you could not.** Say how you checked — dry run output, tests, row counts. That is work they cannot redo in their head, so do it for them. Then name what is still a judgment call: that is the actual question.5. **The case against.** State the strongest reason to reject, and the alternative you ruled out and why. You are not selling the plan.6. **What happens if nobody answers.** Say it, and set `timeout_minutes` to match. `question` is the single thing you need decided; `context` carries 2–6. Don't paste a 400-line diff and ask "does this look right?" — nobody can verify that inreal time, so they will just approve it. Quote the lines that carry the risk and say whatyou did to check the rest. Attach source material with `evidence` (the Slack thread, theemail, the policy excerpt), and send the `body` text, not only a link: a link can changeafter the decision, and the stored snapshot is what the audit trail keeps. Thin ask (don't): request_decision(title: "Cleanup", question: "OK to drop the old table?", context: "Part of the migration. Should be safe.") Same ask, decidable (do): see the example under Filing below. ## Spend friction where the stakes are The default `response_type: "approval"` is right for most asks. For the irreversibleones, make the answer require engagement: - Real alternatives instead of yes/no: `response_type: "select"` with the actual choices ("Drop it", "Archive to cold storage first", "Leave it").- A read-back: `response_type: "text"` asking them to type the thing being destroyed or the amount being spent, so the answer proves they read the ask. Use these sparingly. They work because they cost attention; applied to routine asks theyonly train people to click through. ## Who you ask Name a person or a policy — `approvers` (emails) or `policy` (a policy key). A decisionaddressed to a specific, accountable person gets read; one broadcast to everyone getsread by nobody. ## Then wait, and stop if told to At the start of a run, call `list_pending_decisions` first. It picks up decisionsanswered while you were away or before your context was reset. 1. Wait with `await_decision`. They may be away from their keyboard; that's expected. If it returns `timed_out: true`, call it again. That is normal, not a failure.2. **Don't end your turn while a decision is open** unless something will read the verdict back. A verdict does not wake you. Before you stop, either start a background watcher or scheduled wake-up that calls `check_decision`, or save the `decision_id` where your next run will find it. Saying "still pending" and stopping drops the task.3. Act only on `approved`. The `note` is their actual answer — read it and follow it. For `select`/`text` the answer is in `response_value`.4. On `rejected` or `expired`: **stop.** Report what you did, what you did not do, and what state things are in. Do not route around the rejection with a different method. Ask again only with new information, not the same ask reworded.5. If the question became moot, `cancel_decision` — don't leave it in their inbox. ## Filing: workflow and step - `workflow` = the project or effort: the repo name (`payments-api`), or the named effort (`q3-vendor-onboarding`). Lowercase kebab-case, the **same string every time**, no ids, dates, versions or environments.- `step` = this specific decision: `deploy-v2.3-prod`, `drop-legacy-orders-table`. Example: request_decision( title: "Drop legacy_orders (1.2M rows, irreversible)", question: "Drop legacy_orders, or archive it to cold storage first?", context: "Migration 0071 moved orders to orders_v2; the app no longer reads legacy_orders.\n" + "Verified: 0 reads in 30d of query logs; row counts match orders_v2 (1,204,881\n" + "both); staging dry run succeeded.\n" + "Could not verify: whether Finance's quarterly export reads the table directly —\n" + "that's outside our logs, and it's the judgment call here.\n" + "Against dropping: no backup older than 7d, so a Finance dependency becomes\n" + "unrecoverable after that window. Archiving first costs ~$4/mo and one migration.\n" + "If this expires I stop and leave the table in place.", response_type: "select", options: [{ label: "Drop it" }, { label: "Archive to cold storage first" }, { label: "Leave it" }], tool_name: "run_sql", tool_args: { statement: "DROP TABLE legacy_orders" }, risk: { severity: "high", reversible: false, impact: [{ label: "Rows deleted", value: "1,204,881" }], if_wrong: "No backup older than 7 days; after that, unrecoverable." }, links: [{ label: "Migration 0071", url: "https://github.com/acme/payments-api/pull/412" }], workflow: "payments-api", step: "drop-legacy-orders-table", timeout_minutes: 240 )
A skill is still the model choosing to ask. For steps that must never run unapproved, add the gate hook as well.
#Enforce approval on specific tools (hook)
The tools above are model-elected: the agent chooses to call request_decision. To make approval non-bypassable for a set of tools, wire the gate command as a Claude Code PreToolUse hook. The hook's matcher is your list of gated tools: any matching call is intercepted, Ratifia opens a decision (as a Tool call panel showing exactly what would run), and the tool is blocked until a human approves, and denied otherwise.
In ~/.claude/settings.json (or a project .claude/settings.json):
{ "hooks": { "PreToolUse": [ { "matcher": "Bash|deploy_.*|delete_.*", "hooks": [ { "type": "command", "command": "npx -y @ratifia/mcp gate", "timeout": 300 } ] } ] }}
#Why the command takes no arguments
Claude Code pipes the tool call to the hook on stdin — tool_name, tool_input, plus cwd, session_id, permission_mode and the agent type — so gate reads the specifics from the harness rather than from flags. Everything else (which org, who reviews) comes from the environment: the hook inherits your shell, so export the same config the MCP server uses (RATIFIA_API_KEY, optionally RATIFIA_API_URL / RATIFIA_APPROVER_EMAIL / RATIFIA_POLICY / RATIFIA_WORKFLOW).
#What the reviewer sees
- Tool call — the tool and the exact arguments that would run.
- Where — repo and branch, working directory, agent type, permission mode and a short session id, so "run
kubectl delete ns prod" isn't judged without knowing where it would run. (0.10.0+) - What the user asked for — the request behind the tool call. Off by default: the gate sends metadata, not your conversation. Set
RATIFIA_GATE_INCLUDE_PROMPT=1to include it.
Unlike request_decision, the gate has no model-written reasoning to pass on — no model chose to ask — so this is deliberately everything the harness knows and nothing more.
| Variable | Purpose |
|---|---|
RATIFIA_GATED_TOOLS | Optional comma-separated allow-list checked inside the gate, letting you use a broad matcher and narrow here (e.g. deploy_prod,delete_database). Unset = gate everything the matcher sends. |
RATIFIA_GATE_TIMEOUT_SEC | How long to block waiting for a human (default 240). Keep the hook timeout a bit higher. |
RATIFIA_GATE_INCLUDE_PROMPT | 1 = include the user's last request (read from the session transcript, truncated) in the decision. Default off: the gate sends only metadata. |
RATIFIA_GATE_FAIL_OPEN | 1 = allow the tool if Ratifia is unreachable or the wait times out. Default is fail-closed (deny), because a gate that fails open is no gate. |
On approval the tool runs; on rejection it's blocked and the reviewer's note is returned to the agent as the reason. This is the enforcing complement to request_decision: the harness runs the hook whether or not the model chose to ask.
#FAQ
#My agent opened a decision and then never came back for the verdict.
This is the most common failure, and it is almost never a bug in Ratifia — the agent's turn simply ended while the decision was still open. A verdict does not wake a sleeping agent. request_decision hands back a decision_id and nothing pushes to the agent afterwards; if it doesn't hold the thread itself, the human answers into the dashboard and no one ever reads it.
Which way you hold it depends on how long the wait is:
| Your agent | Do this | Not this |
|---|---|---|
| Runs one long turn, human is at their keyboard | await_decision immediately after request_decision, and call it again whenever it comes back timed_out: true | Polling check_decision in a loop |
| Runs in discrete cycles (cron, queue worker, scheduled job) | Persist the decision_id to durable state, end the turn, and have the next cycle call check_decision | await_decision — it burns the whole cycle and the harness may kill it mid-wait |
The second row is the one that bites. If the human is away from their keyboard, a decision can sit for hours; an agent that blocks on it is an agent that is doing nothing else, and one that does not block but also doesn't record the decision_id has silently dropped the task on the floor.
If your harness has timers or scheduled wake-ups, set one before you call request_decision, not after — a turn can end before you get to the second call.
#How does an agent recover a decision it forgot about?
list_pending_decisions is the agent's inbox. Call it at the start of every run, before anything else. It is the only thing that closes the loop when an agent asked for a decision and then lost its context — compaction, a new session, a redeploy, a crashed process. Without it the agent either waits forever on a verdict it will never read, or re-asks and opens a duplicate decision for work that was already approved.
Treat a non-empty result as work to finish, not as noise.
#My agent went ahead and did the risky thing without asking.
request_decision is model-elected — the agent decides to call it, and an agent under pressure can decide not to. If a step must never run unapproved, don't rely on the model choosing well: wire the gate hook. The harness runs it whether or not the model thought to ask, and it fails closed.
#request_decision came back with approval_required: false. Did it break?
No — an org policy matched and auto-resolved that no human approval was needed. Proceed with the action. There is nothing to wait for and no decision to check.
#The human answered, but the agent ignored what they said.
The verdict is not the whole answer. Read the note — that is the human's actual reply, and it often changes how to do the approved thing. If you asked for a choice or a typed value, the answer is in response_value (map selected option ids back through response_spec.options), and if you passed a proposed_output, the text to act on is output.content — the human's refined version — not the draft you sent.
#Install options
Published on npm as @ratifia/mcp. The npx -y @ratifia/mcp config shown above fetches and runs it, no clone required. It needs Node 22 or newer on the machine that launches it.
For development, run from a local clone instead. Run npm install && npm run build, then point the entry at the built file:
{ "mcpServers": { "ratifia": { "command": "node", "args": ["/absolute/path/to/ratifia-mcp/dist/index.js"], "env": { "RATIFIA_API_KEY": "your-org-worker-api-key" } } }}