Docs

#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 URLhttps://mcp.ratifia.com/mcp
Sign-inOAuth 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.

text
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:

json
{  "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

VariableRequiredDefaultPurpose
RATIFIA_API_KEY✅noneOrg-scoped worker API key (from the dashboard).
RATIFIA_API_URLhttps://api.ratifia.comAPI base; point at a different environment.
RATIFIA_APP_URLhttps://app.ratifia.comDashboard base for the decision links returned to the agent.
RATIFIA_APPROVER_EMAILnoneWithout 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_POLICYnoneThe 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_WORKFLOWratifia-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

ToolWhat it does
request_decisionOpen 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_decisionBlock 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_decisionPoll a decision's status once.
list_pending_decisionsThe agent's inbox: what's outstanding.
cancel_decisionWithdraw a decision the agent no longer needs.
attach_evidenceAttach 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 or billing-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-prod or refund-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) and if_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 inside context shows as plain text.
  • evidence: the same items attach_evidence accepts.

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_typeThe human…The agent reads
approval (default)approves or rejectsverdict (+ note)
selectpicks from options you supply (set allow_multiple for many)response_value.selected (ids → labels via response_spec.options)
texttypes a valueresponse_value.text
ts
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.

ts
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.

markdown
---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):

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=1 to 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.

VariablePurpose
RATIFIA_GATED_TOOLSOptional 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_SECHow long to block waiting for a human (default 240). Keep the hook timeout a bit higher.
RATIFIA_GATE_INCLUDE_PROMPT1 = 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_OPEN1 = 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 agentDo thisNot this
Runs one long turn, human is at their keyboardawait_decision immediately after request_decision, and call it again whenever it comes back timed_out: truePolling 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_decisionawait_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:

json
{  "mcpServers": {    "ratifia": {      "command": "node",      "args": ["/absolute/path/to/ratifia-mcp/dist/index.js"],      "env": { "RATIFIA_API_KEY": "your-org-worker-api-key" }    }  }}