> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# 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](/user-guide/tools/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](/developer-guides/guides/runtime-tools#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](#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](#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`**

```json title="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](#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](/user-guide/products-surfaces/mcp-authentication#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](#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`**

```typescript title="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](/user-guide/products-surfaces/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](#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](#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](#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`**

```json title="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`**

```json title="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`**

```json title="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:

| Field                            | Contents                                                                                                                                                                                                                                                          |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_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_approval` | If 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`. |
| `requestState`                   | A 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.code`                   | Cause                                                                                                                 |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `APPROVAL_STATE_INVALID`      | The `requestState` was changed or isn't valid.                                                                        |
| `APPROVAL_STATE_EXPIRED`      | The `requestState` is past `expiresAt`. Call the tool again from the start.                                           |
| `APPROVAL_STATE_MISMATCH`     | The retry used different arguments or a different credential, or the paused call changed.                             |
| `APPROVAL_ALREADY_DECIDED`    | Someone already answered the approval.                                                                                |
| `APPROVAL_DECISION_MISSING`   | The retry has no `inputResponses.runtype_approval`.                                                                   |
| `APPROVAL_OWNER_REQUIRED`     | The gate doesn't set `approver` to `end-user`, so only the Product owner can answer it.                               |
| `APPROVAL_RESUME_UNAVAILABLE` | The 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`**

```json title="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`**

```json title="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`**

```json title="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.code`                   | Cause                                                                                                                       |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `APPROVAL_DECISION_MISSING`   | `inputResponses` has no answer under the key of the pending approval.                                                       |
| `APPROVAL_ALREADY_DECIDED`    | The key names an approval that isn't pending anymore, or the approval was already answered or expired. Read the task again. |
| `APPROVAL_OWNER_REQUIRED`     | The gate is an owner gate, so only the Product owner can answer it.                                                         |
| `APPROVAL_RESUME_UNAVAILABLE` | The server couldn't resume the run. `data.retryable` is `true`, so send the same answer again.                              |

For other codes, see [Handle a refused retry](#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:

* [Tool approvals](/user-guide/tools/tool-approvals): require approval for tools and answer it in the dashboard
* [Approvals on messaging surfaces](/user-guide/products-surfaces/approvals-on-messaging-surfaces): approve tool calls from Slack and Telegram
* [Runtime tools developer guide](/developer-guides/guides/runtime-tools#let-the-chat-visitor-approve-a-tool): configure an `end-user` approval gate