MCP 2025-06-18

approval_request

Request a human decision. Advisory proposals record the decision but execute nothing; supported command proposals execute atomically only after approval. Link the request to your session with sessionId so the session shows as waiting. An agent_request may ask a question instead: send question {} for a free-text answer or { choices } for up to 6 options. The answer appears in approval_status and, with a sessionId, as an instruction on your next session_heartbeat. With expiresInMinutes, an unresolved request expires and a command proposal never executes.

Input schema

This schema is shared with tools/list. The server also verifies current scopes and resource-level access before returning data or changing a record.

Synthetic example · JSON

{
  "type": "object",
  "properties": {
    "kind": {
      "enum": [
        "work_change",
        "memory_change",
        "life_change",
        "agent_request"
      ]
    },
    "title": {
      "type": "string",
      "description": "Approval title"
    },
    "description": {
      "type": "string",
      "description": "What will change and why"
    },
    "targetType": {
      "type": "string",
      "description": "Optional target type"
    },
    "targetId": {
      "type": "string",
      "description": "Optional target ID"
    },
    "proposal": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "mode": {
              "const": "advisory"
            }
          },
          "required": [
            "mode"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "mode": {
              "const": "command"
            },
            "command": {
              "type": "object",
              "properties": {
                "method": {
                  "const": "work_move"
                },
                "input": {
                  "type": "object",
                  "properties": {
                    "itemId": {
                      "type": "string",
                      "description": "Work item ID"
                    },
                    "columnKey": {
                      "type": "string",
                      "description": "Destination column key"
                    }
                  },
                  "required": [
                    "itemId",
                    "columnKey"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "method",
                "input"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "mode",
            "command"
          ],
          "additionalProperties": false
        }
      ],
      "description": "Explicitly advisory, or a typed command from the supported executable subset."
    },
    "sessionId": {
      "type": "string",
      "description": "Optional ID of one of this agent's open sessions"
    },
    "expiresInMinutes": {
      "type": "integer",
      "minimum": 5,
      "maximum": 10080,
      "description": "Optional. Minutes until the request expires, from 5 to 10,080 (7 days)."
    },
    "question": {
      "type": "object",
      "properties": {
        "choices": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "minItems": 2,
          "maxItems": 6,
          "description": "Distinct options. Omit for a free-text answer."
        }
      },
      "additionalProperties": false,
      "description": "Optional, agent_request with an advisory proposal only. The title is the question."
    },
    "idempotencyKey": {
      "type": "string",
      "description": "Unique retry key"
    }
  },
  "required": [
    "kind",
    "title",
    "proposal",
    "idempotencyKey"
  ],
  "additionalProperties": false
}

Call this tool

Use the tool name below in params.name. Supply the exact arguments described above; this envelope deliberately leaves required resource values for your authorized context.

Synthetic example · JSON

{
  "jsonrpc": "2.0",
  "id": "example_request",
  "method": "tools/call",
  "params": {
    "name": "approval_request",
    "arguments": {}
  }
}

Read the result before continuing

Inspect protocol errors and the tool result’s isError flag. A request being accepted is not proof of an external action completing. Preserve correlation IDs and unchanged mutation idempotency keys across safe retries.