Skip to navigation

Approvals on MCP surfaces

When an Agent behind an MCP Surface wants to run a tool that needs approval, the tool call pauses. The person who uses the client can see the tool and its exact parameters, then approve or deny the call. The run then continues with that decision.

This page describes how a call pauses and how to answer it: in the client, in a browser, and inside an MCP task. It ends with the MCP format for client authors. For approvals in general, see Tool approvals.

Before you begin

A call can pause for the client only when all of these conditions are true:

  • The Capability is backed by a Runtype Agent whose approval gate sets approver to end-user. For how to set it, see Let the chat visitor approve a tool.
  • The Agent’s own gate is its only approval gate. If a Skill, a nested Flow, or a subagent that the Agent uses has an approval gate, the call returns an error.
  • The client sends MCP requests in protocol revision 2026-07-28 and declares that it supports form elicitation. For the request format, see MCP format for client authors.

A signed-in user’s client that doesn’t declare form elicitation can get an approval link instead, and a Surface can require that link for every call. For more information, see Approve in a browser.

Use an end-user gate only when the gate asks for the user’s consent, such as sending an email on the user’s behalf. If the gate enforces your own policy or budget, such as refunds or credits, keep it an owner gate. A user must not approve their own exception.

The following Agent configuration lets the client approve send_email:

Agent config
{
"tools": {
"approval": {
"require": ["send_email"],
"approver": "end-user"
}
}
}

Calls that can’t pause

Some calls return an error instead of a paused call. The error says that the Capability paused for human approval and can’t complete over MCP. This happens in these cases:

  • The gate has no approver, so only the Product owner can answer it.
  • The client doesn’t use revision 2026-07-28, or doesn’t declare form elicitation and no user is signed in.
  • The Surface sets approvals.grantFrom to out_of_band, and the client uses an API key, so no signed-in user can approve the call.
  • The Agent sets durability.forced to durable, and the call doesn’t run as an MCP task that can pause for approval. For those tasks, see Approvals inside MCP tasks.
  • The Agent is a Claude Managed Agent or an external Agent.
  • The Capability is a Flow.

To run such a Capability over MCP, remove the tool from the Agent’s approval list, or call the Capability from a Surface that carries approvals, such as a chat Surface.

How a gated call pauses

When the Agent wants to run a gated tool, the server stops the run before the tool runs and returns the pending call to the client. The pending call has these parts:

  • Tool: the name of the gated tool.
  • Parameters: the exact parameters that the tool will run with. Hidden parameter values and secrets are redacted.
  • Parameters hash: a SHA-256 hash of the parameters. An approval applies only to the parameters with this hash.
  • Reason: the Agent’s own explanation. Runtype doesn’t verify it, so the client labels it as unverified.
  • Expiry: the pending call expires after one hour.

When you approve, the tool runs with those exact parameters. When you deny, the tool doesn’t run, the Agent learns that the call was denied, and the run continues without it. A run can pause again for the next gated call.

Approve in a browser

When a client can’t answer an approval itself, the paused call can carry an approval link instead. The signed-in user opens the link, reviews the tool call, and approves or denies it. The client then retries the call, and the run continues with that decision.

A call gets an approval link when all of these conditions are true:

  • The caller is a signed-in user: the client sends an mcpu_ access token to a Surface that uses Sign-in required. For more information, see What happens when a user signs in.
  • The client sends MCP requests in protocol revision 2026-07-28.
  • The Agent’s approval gate sets approver to end-user.
  • The Surface sets approvals.grantFrom to out_of_band, or the client doesn’t declare form elicitation.

An owner gate never gets an approval link.

How the user approves the call

When the user opens the approval link, the following steps happen:

  1. The page emails a sign-in link to the address of the user who made the tool call. If the Surface uses your own identity provider, the page sends the user there instead. Only that user can sign in and approve the call.
  2. After sign-in, the page shows the tool name, all of its parameters with hidden values redacted, the parameters hash, and the Agent’s reason, labeled as unverified.
  3. The user approves or denies the call. The decision applies only to the call with that parameters hash.

Runtype doesn’t use the Agent’s reason for any decision. The approval link expires one hour after the call paused.

Require browser approval for every call

The approvals.grantFrom setting in the Surface’s behavior controls who answers end-user approvals. It accepts these values:

  • client: The default. A client that declares form elicitation answers in band, as described in MCP format for client authors. Other signed-in clients get an approval link.
  • out_of_band: Every qualifying call gets an approval link, so an Agent can’t approve its own tool call. A client that can show the approval form still gets the link, and the server ignores its in-band answers.

On an out_of_band Surface, a client that uses an API key gets an error, because no user is signed in to approve the call. Use out_of_band with Sign-in required. For an MCP Surface, open the Surface’s Keys tab in the dashboard and turn on Require approvals on a hosted page, which appears when the Surface uses Sign-in required. The following example sets both in code:

TypeScript SDK
import { defineSurface } from '@runtypelabs/sdk'
export const supportMcp = defineSurface({
name: 'Support MCP',
type: 'mcp',
behavior: {
authMode: 'required',
approvals: { grantFrom: 'out_of_band' },
},
status: 'active',
})

For how to apply a definition, see Manage surfaces as code. If a call paused for an in-band answer before you switched a Surface to out_of_band, its retry returns APPROVAL_STATE_EXPIRED, and the client calls the tool again.

Approvals inside MCP tasks

A call that runs as an MCP task pauses inside the task. The task’s status changes to input_required, and the run waits on the server until someone answers. Each status check of the task (tasks/get) returns the pending approval, with the same tool, parameters, parameters hash, and reason as a paused call. After the answer, the run continues in the same task, and the next gated call can pause it again.

The client answers a paused task with a tasks/update request. For the MCP format, see Answer a paused task.

A paused task doesn’t use the one-hour limit of a paused call. The approval’s expiresAt field gives the time when it expires.

Who can answer a paused task

Besides the conditions in Before you begin, a task asks its client for an answer only when all of these conditions are true:

  • The tools/call that started the task declared form elicitation. Later requests for the same task don’t need to declare it.
  • The gate sets approver to end-user and requires approval for the paused tool. A Skill load never qualifies.
  • The Surface doesn’t set approvals.grantFrom to out_of_band. On a Surface that requires browser approval, a task never asks its client, and tasks/update can’t answer it.

Runtype checks the gate in two places: the approval policy that the run started with, and the Agent version that the run executed. Both must set approver to end-user for the paused tool. A change to the Agent after the run starts can’t turn an owner gate into an end-user gate. If the Agent version that the run executed no longer exists, the gate counts as an owner gate.

When a task can’t ask its client, it finishes with an error result that says that the Capability paused for human approval. On a Surface that sends approvals to a browser, the call can instead pause with an approval link before the server starts a task. For the conditions, see Approve in a browser.

MCP format for client authors

This section is for developers who build their own MCP client. It covers in-band approvals, approvals in a browser, and approvals inside MCP tasks.

Declare support

Send each tools/call in protocol revision 2026-07-28, and declare form elicitation in the request’s _meta:

Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "Support_Agent",
"arguments": { "message": "Tell the customer that order ord_123 shipped" },
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": { "elicitation": { "form": {} } }
}
}
}

Read the input_required result

When the call pauses, the result has resultType set to input_required:

Result
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"resultType": "input_required",
"inputRequests": {
"runtype_approval": {
"method": "elicitation/create",
"params": {
"mode": "form",
"message": "Approve the call to \"send_email\"?\nParameters: {\"subject\":\"Your order shipped\",\"to\":\"pat@example.com\"}\nParameters hash: 3f9a2b7c1d4e\nThe agent says (unverified): The customer asked for a shipping update.",
"requestedSchema": {
"type": "object",
"properties": {
"decision": { "type": "string", "title": "Decision", "enum": ["approve", "deny"] }
},
"required": ["decision"]
}
}
}
},
"requestState": "REQUEST_STATE",
"_meta": {
"io.runtype/approval": {
"approvalId": "APPROVAL_ID",
"toolName": "send_email",
"parameters": { "to": "pat@example.com", "subject": "Your order shipped" },
"paramsHash": "PARAMS_HASH",
"reason": "The customer asked for a shipping update.",
"expiresAt": "2026-11-08T13:00:00.000Z"
}
}
}
}

The result has these fields:

  • inputRequests.runtype_approval: a form elicitation with one field, decision, whose value is approve or deny. Its message names the tool and shows its parameters, the first 12 characters of the parameters hash, and the Agent’s reason, labeled as unverified. A client that renders any form elicitation can show it.
  • _meta["io.runtype/approval"]: the approval details. paramsHash is the SHA-256 hash of parameters as canonical JSON, with object keys sorted by code unit. parameters has hidden values and secrets redacted. reason is the Agent’s own claim, and Runtype doesn’t verify it.
  • requestState: a signed value. Send it back unchanged. It expires at expiresAt, one hour after the pause.

Send the decision

To answer, send the same tools/call again with the same name, arguments, and credential. Add requestState and inputResponses.runtype_approval:

Retry
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "Support_Agent",
"arguments": { "message": "Tell the customer that order ord_123 shipped" },
"requestState": "REQUEST_STATE",
"inputResponses": {
"runtype_approval": { "action": "accept", "content": { "decision": "approve" } }
},
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": { "elicitation": { "form": {} } }
}
}
}

Only "action": "accept" with "decision": "approve" approves the call. Any other answer, including decline and cancel, denies it. The retry returns the run’s result, or another input_required result if the run pauses again.

To record how the user answered, add grantSource to _meta["io.runtype/approval"] in the retry. Its value is prompt, flag, answers, or url. Runtype records it for audit only.

Read a browser approval

A paused call that carries an approval link differs from the in-band result in these fields:

FieldContents
_meta["io.runtype/approval"]The same fields as the in-band result, plus approvalUrl (the approval link), grantFrom set to out_of_band, and status set to pending.
inputRequests.runtype_approvalIf the client declares URL-mode elicitation (elicitation.url in its capabilities), a URL-mode elicitation with mode set to url, the approval link in url, and a message. Otherwise, the result has no inputRequests, and the link is only in _meta.
requestStateA signed value. Send it back unchanged.

The approval link is the Surface’s MCP URL followed by /oauth/approvals/ and a token. Show the link to the user.

To continue the run, send the same tools/call again with the same arguments and the requestState. The server ignores inputResponses for a browser approval. Until the user decides, each retry returns the same result, so retry every few seconds without prompting the user again. After the user decides, the next retry resumes the run with that decision. If browser approvals are turned off for the Surface while the call waits, the retry returns APPROVAL_RESUME_UNAVAILABLE.

Handle a refused retry

The server refuses a retry with JSON-RPC error -32602. The data.code field gives the reason. If data.retryable is true, send the same retry again later.

data.codeCause
APPROVAL_STATE_INVALIDThe requestState was changed or isn’t valid.
APPROVAL_STATE_EXPIREDThe requestState is past expiresAt. Call the tool again from the start.
APPROVAL_STATE_MISMATCHThe retry used different arguments or a different credential, or the paused call changed.
APPROVAL_ALREADY_DECIDEDSomeone already answered the approval.
APPROVAL_DECISION_MISSINGThe retry has no inputResponses.runtype_approval.
APPROVAL_OWNER_REQUIREDThe gate doesn’t set approver to end-user, so only the Product owner can answer it.
APPROVAL_RESUME_UNAVAILABLEThe server couldn’t resume the run. data.retryable is true, and the requestState stays valid until expiresAt.

Answer a paused task

A task can ask for an approval only when the tools/call that starts it declares both the tasks extension and form elicitation:

Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "Support_Agent",
"arguments": { "message": "Tell the customer that order ord_123 shipped" },
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {
"extensions": { "io.modelcontextprotocol/tasks": {} },
"elicitation": { "form": {} }
}
}
}
}

When the run pauses, tasks/get returns the task with status set to input_required. If the run pauses before the tools/call returns, the call returns the same task at once, with resultType set to task. The following example shows a paused task:

tasks/get result
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"taskId": "TASK_ID",
"status": "input_required",
"statusMessage": "Waiting for approval to call \"send_email\"",
"createdAt": "2026-11-08T12:00:00.000Z",
"lastUpdatedAt": "2026-11-08T12:00:04.000Z",
"ttlMs": 86400000,
"pollIntervalMs": 5000,
"inputRequests": {
"runtype_approval:APPROVAL_ID": {
"method": "elicitation/create",
"params": {
"mode": "form",
"message": "Approve the call to \"send_email\"?\nParameters: {\"subject\":\"Your order shipped\",\"to\":\"dana@example.com\"}\nParameters hash: 3f9a2b7c1d4e",
"requestedSchema": {
"type": "object",
"properties": {
"decision": { "type": "string", "title": "Decision", "enum": ["approve", "deny"] }
},
"required": ["decision"]
}
}
}
},
"_meta": {
"io.runtype/approval": {
"approvalId": "APPROVAL_ID",
"toolName": "send_email",
"parameters": { "to": "dana@example.com", "subject": "Your order shipped" },
"paramsHash": "PARAMS_HASH",
"expiresAt": "2026-11-08T12:05:04.000Z"
}
}
}
}

The form elicitation and _meta["io.runtype/approval"] have the same shape as in an input_required result. The task has no requestState, because the task ID identifies the paused run. The key of the input request is runtype_approval: followed by the approval ID, so each approval in the task has its own key.

To answer, send tasks/update with the task ID and an inputResponses entry under that key:

tasks/update
{
"jsonrpc": "2.0",
"id": 3,
"method": "tasks/update",
"params": {
"taskId": "TASK_ID",
"inputResponses": {
"runtype_approval:APPROVAL_ID": { "action": "accept", "content": { "decision": "approve" } }
},
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {
"extensions": { "io.modelcontextprotocol/tasks": {} }
}
}
}
}

Send tasks/get and tasks/update with the credential that started the task. Decisions work as in a retry: only "action": "accept" with "decision": "approve" approves the call, and you can add grantSource to _meta["io.runtype/approval"]. The server answers with an empty result and resumes the run in the background. Keep polling tasks/get: the task reports working, then its result, or input_required again with a new key for the next approval.

The server refuses a tasks/update with JSON-RPC error -32602. The data.code field gives the reason:

data.codeCause
APPROVAL_DECISION_MISSINGinputResponses has no answer under the key of the pending approval.
APPROVAL_ALREADY_DECIDEDThe key names an approval that isn’t pending anymore, or the approval was already answered or expired. Read the task again.
APPROVAL_OWNER_REQUIREDThe gate is an owner gate, so only the Product owner can answer it.
APPROVAL_RESUME_UNAVAILABLEThe server couldn’t resume the run. data.retryable is true, so send the same answer again.

For other codes, see Handle a refused retry. Without data.code, the error message gives the reason. For example, the task isn’t waiting for input, or the call that started it didn’t declare form elicitation.

Next steps

Continue with one of these guides: