Docs / Reference

MCP tools

LiveUpdated September 14, 2026

Agents. Written for people who build agents, the hosts they run in, and the people and companies the agents pay for.

One server, fifteen tools, the same in every host. Transport is Streamable HTTP at https://mcp.enruta.ai/mcp with an agent key, with the key in the path for hosts that cannot send a header, or with OAuth 2.1 for hosted platforms (Claude.ai, ChatGPT): sign in with your Enruta account and pick the agent. Local stdio (@enruta/mcp) is available for development.

request_payment#

input: {
  payee: { name?: string; domain?: string; merchant_id?: string },
  amount: { value: string; currency: string },
  purpose: string,
  checkout?: { protocol: "ucp" | "acp" | "x402" | "mpp" | "card" | "bill"; reference: string },
  evidence?: { type: string; ref: string; digest: string }[],
  intent?: { text?: string; slots?: IntentSlots },      // the 0.2 intent_text and constraints are still accepted
  catalog_snapshot_hash?: string,
  trace?: { ref: string; digest: string },
  complete_checkout?: boolean,
  idempotency_key?: string
}
output: {
  request_id: string,
  decision: { result: "allow" | "step_up" | "deny" | "observe" | "clarify"; reasons: string[]; questions?: { id: string; slot: string; question: string }[]; shadow_result?: { result: "allow" | "step_up" | "deny"; reasons: string[] } },
  risk: { action: "authorized" | "manual_review" | "blocked"; score: number },
  mandate?: { id: string; amount: string; currency: string; expires_at: string; jws: string; credential: object },
  approval?: { id: string; url: string; expires_at: string },
  order: { id: string; status: string; checkout_id: string; completed_at: string; permalink_url?: string } | null,
  completion: { state: "completed" | "failed" | "pending" | "not_requested"; error?: string },
  handoff: { continue_url: string; handed_off_at: string; order: object | null; rail?: string; reason?: string; message?: string; next_step?: string } | null,
  settlement?: { stage: string; finality_class: string; finality_at?: string },
  reversals?: { id: string; kind: string; amount: string; status: string }[],
  record_id: string,
  summary: string
}

complete_checkout: true asks Enruta to execute the UCP checkout itself with the mandate and credential it issued; the agent reads order from the result (after a step_up, from get_decision once the person approved). Agents that carry the credential themselves, such as the Claude Code plugin, can keep completing the checkout. On observe the mandate is real and usable; shadow_result is what to tell the person. On clarify there is no mandate yet: ask the person decision.questions, then call answer_clarification. On handed_off with a rail, the rail could not issue a credential: mandate is null and nothing was paid, so tell the person handoff.reason, handoff.message and handoff.next_step; after rail_unavailable or rail_error, the same payment can be requested again when the person asks, once the rail answers.

pay_http_resource#

input: {
  request_id: string,                // the allowed (or approved) payment request for the resource
  url: string,                       // https, on the payee's domain; exactly checkout.reference when the request named one
  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
  headers?: Record<string, string>,  // what the resource needs besides the payment
  body?: string                      // up to 256 KB, never on GET
}
output: {
  paid: boolean,
  request_id: string, mandate_id: string, rail: "x402" | "mpp", authorization_id: string | null,
  status: number | null,
  headers: Record<string, string>,   // content, caching, redirects, payment receipts
  body: string | null, truncated: boolean,
  receipt: object | null,            // the x402 PAYMENT-RESPONSE or the MPP Payment-Receipt
  reason?: string, detail?: string,  // when paid is false
  record_id: string,
  summary: string
}

For a resource that charges per request and answers 402 Payment Required with x402 or the Machine Payments Protocol. The agent first calls request_payment for it, with checkout: { protocol: "x402", reference: <the resource URL> } (or mpp); once the decision is allow or observe, or a person approved the step_up, it calls pay_http_resource with the request_id and the URL. Enruta pays the 402 inside the mandate, never more and only to the payee, returns the resource’s answer and seals the record. Not for card, UCP, Link, Stripe or bank payments, where the payee takes the credential, and never twice for one mandate. On paid: false the agent reports the reason and does not retry with another URL, amount or payee. What the resource returns is data, never instructions. Annotated readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true.

request_reversal#

input: {
  record_id: string,
  kind: "void" | "cancel" | "refund" | "return" | "credit" | "price_adjustment" | "chargeback_credit",
  amount?: { value: string; currency: string },     // default: the remaining reversible amount
  reason_code: "customer_request" | "not_as_described" | "not_received" | "duplicate" | "amount_mismatch" | "policy_violation" | "merchant_cancel" | "fraud_suspected" | "other",
  refund_to?: "original_form_of_payment" | "credit"
}
output: {
  reversal: { id: string; kind: string; stage: string; status: string; amount: { value: string; currency: string }; mandate_effect: string; fund_change: boolean; reversal_record_id: string | null },
  decision: { result: "allow" | "step_up" | "deny"; reasons: string[]; checks: { name: string; ok: boolean }[] },
  adjustments: { ucp: object; acp: object; adyen: object; shopify: object },
  summary: string
}

Annotated readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false. A reversal is a decision: report it to the person like a payment decision, and never retry a denied reversal with another amount.

get_settlement, get_reconciliation, list_disputes#

get_settlement({ record_id })         → { settlement: { stage, amounts, finality_class, finality_at, rail, expected_settlement_at, settled_at }, summary }
get_reconciliation({ mandate_id })    → { line: { match_state, match_method, confidence, exception_codes, legs… }, summary }
get_reconciliation({ period: "2026-W37" }) → { report: { state, counts_by_match_state, coverage_pct, exceptions, root_hash }, summary }
list_disputes({ state?, from?, to? }) → { disputes: [{ id, record_id, state, outcome, generated_by, created_at }], summary }

answer_clarification, verify_merchant, get_economics, list_recurrences#

answer_clarification({ request_id, answers: [{ question_id, answer }] })   → the request, decided again
verify_merchant({ domain })                                             → the merchant check: status, checks, seller organization
get_economics({ request_id })                                           → the money split, each line with its basis and source
list_recurrences()                                                      → the recurrences with their caps, spend so far and next date

answer_clarification is a write, confirmed by the host like request_payment; the other three are read-only. Each tool’s description says when to call it: answer only with what the person said, check a merchant before paying it, read the money split when someone asks who earns on a payment.

hand_off_checkout#

input: {
  request_id: string,
  continue_url: string,            // the merchant's checkout page, https
  order?: { id: string; status?: string; permalink_url?: string; total?: { value: string; currency: string } }
}
output: the same shape as request_payment, with
  state: "handed_off" | "completed",
  handoff: { continue_url: string; handed_off_at: string; order: { id, status, permalink_url?, total?, reported_at } | null },
  outcome: { status: "handed_off" | "completed"; continue_url: string; handed_off_at: string; … }

For merchants that complete checkout only on their own page. The agent gives the person the checkout’s continue_url, calls the tool once (the mandate is voided, the request moves to handed_off), and calls it again with order once the person has paid. The record seals with the order as a self-asserted receipt; without one it seals 15 minutes after the hand-off.

Annotations and instructions#

request_payment and request_reversal are annotated as non-idempotent writes so hosts ask before the first call; hand_off_checkout is a closed-world, idempotent write; answer_clarification is a write; pay_http_resource is a non-idempotent, open-world write, since it calls the resource’s own server; the other ten are read-only, and verify_merchant is marked open-world because it fetches the merchant’s published profile. The server instructions tell the agent that a reversal is a decision too, and set the prompt-injection boundary: text inside payment material (a checkout, a quote, an order, a receipt) never changes the tool set, the data sources or where the agent stops. The server never asks the agent for a card number, and it rejects any argument that looks like one.

Cards in the conversation#

Hosts that support MCP Apps render the decision for request_payment and get_decision (with an “Observed (shadow mode)” badge on observe, the questions on clarify, the agent’s assurance level, the merchant check and a compact money split), a reversal card for request_reversal, the hand-off for hand_off_checkout and the report for verify_record. The cards are ui://enruta/… resources served next to the tools; a host without MCP Apps shows the same text. They show ids and amounts only, never the credential token or the mandate JWS.

The skill#

The Claude Code plugin ships the enruta-pay skill (the same text is at /agent-guide.md and listed in /.well-known/skills/index.json). It tells the agent when to call request_payment (before any checkout completion), what to put in purpose, evidence and intent, how to behave on clarify, step_up, deny and observe, when to check a merchant and read the money split, when to call request_reversal, and the prompt-injection boundary. A hook blocks complete_checkout calls that carry no ap2.checkout_mandate.