Make an agent wait for a human with MCP tasks.

A tool call is meant to return in seconds. A person answers in minutes, hours or days. The Tasks extension of the Model Context Protocol closes that gap: the call returns a task at once, and the client checks back until the person has answered.

For developers8 min readUpdated

The problem: a tool that waits for a person

Your agent reaches a point where it needs a person: a fact only a colleague knows, a choice between two drafts, a yes before a release. It calls a tool that sends the question. Then what?

  • Hold the call open until the answer arrives. HTTP requests, proxies and AI clients all time out long before a person answers.
  • Return at once with an id, and let the agent ask again later with another tool. That works everywhere, but the agent has to remember to check, and the client doesn't know the work is still going on.
  • Return a task. The call ends at once with a task id, the client knows the result is coming, and it polls the server on its own until the task completes.

The third way is what MCP tasks are for. This guide shows it with ask_person, the Guizzo tool that sends a question to people by email, but the same calls work for any tool a server runs as a task.

How MCP tasks work

Tasks are an extension of MCP, named io.modelcontextprotocol/tasks. On protocol version 2026-07-28, each request carries the client's capabilities in its _meta, so the client declares the extension request by request. A server that supports it can then answer a tools/call with a task instead of the tool's result.

MethodWhat it does
tools/callStarts the work. The result is a task with resultType: "task", a taskId and the status working.
tasks/getReads the task. Once its status is completed, it carries the tool's result, in the tool's own output schema.
tasks/cancelStops the work. In Guizzo, it closes the question so nobody can answer it any more.

The server decides, call by call, whether a tool becomes a task. In Guizzo, ask_person and request_approval do once the request is sent; every other tool answers as usual.

Tasks need protocol version 2026-07-28. A client on 2025-11-25 gets a plain result, and reads the answer later as described in the fallback below.

Step by step, with curl

A client with tasks does all of this for you. Writing the calls by hand shows what goes over the wire, and it is how a script or a background agent without an MCP client can use tasks.

  1. 1
    Get an API keySign in to the Guizzo dashboard and create a key under Access. A key acts as the person who created it, in one workspace. Agents in an AI app connect with OAuth instead, and their app sends the same calls.
  2. 2
    Call the tool, declaring the extensionSend tools/call with an empty object for io.modelcontextprotocol/tasks in the client capabilities.
  3. 3
    Keep the task idThe answer is a task with the status working. Its taskId is the Guizzo request id.
  4. 4
    Poll with tasks/getCall tasks/get every pollIntervalMs until the status is no longer working.
  5. 5
    Read the resultA completed task carries the tool's result: the answers, or the status expired if nobody answered in time.

Here is the call that sends the question. It asks Giulia a yes or no question, open for 8 hours:

sh
curl https://mcp.guizzo.ai/mcp \
  -H "Authorization: Bearer $GUIZZO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: ask_person" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
    "name":"ask_person",
    "arguments":{
      "to":["giulia@example.com"],
      "title":"Can we ship on Friday?",
      "fields":[{"type":"boolean","name":"ship","label":"Ship on Friday"}],
      "expires_in_hours":8
    },
    "_meta":{
      "io.modelcontextprotocol/protocolVersion":"2026-07-28",
      "io.modelcontextprotocol/clientInfo":{"name":"release-bot","version":"1.0.0"},
      "io.modelcontextprotocol/clientCapabilities":{
        "extensions":{"io.modelcontextprotocol/tasks":{}}
      }
    }}}'

Guizzo emails Giulia, charges one credit and answers with a task instead of the usual result:

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "task",
    "taskId": "req_01JD3F6Q8V2X4N7K9M5T1W0Y3Z",
    "status": "working",
    "statusMessage": "Waiting for answers.",
    "createdAt": "2026-11-17T09:12:04.512Z",
    "lastUpdatedAt": "2026-11-17T09:12:04.512Z",
    "ttlMs": 2620800000,
    "pollIntervalMs": 30000
  }
}

Then ask for the task by its id. The headers are the same, with Mcp-Method: tasks/get and the task id as Mcp-Name; the request must declare the extension again, since every request carries its own capabilities:

json
{"jsonrpc":"2.0","id":2,"method":"tasks/get","params":{
  "taskId":"req_01JD3F6Q8V2X4N7K9M5T1W0Y3Z",
  "_meta":{
    "io.modelcontextprotocol/protocolVersion":"2026-07-28",
    "io.modelcontextprotocol/clientInfo":{"name":"release-bot","version":"1.0.0"},
    "io.modelcontextprotocol/clientCapabilities":{
      "extensions":{"io.modelcontextprotocol/tasks":{}}
    }
  }}}

While Giulia hasn't answered, the status stays working and there is no result. Once she answers, the task completes and carries what ask_person would have returned, with the answers:

json
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "resultType": "complete",
    "taskId": "req_01JD3F6Q8V2X4N7K9M5T1W0Y3Z",
    "status": "completed",
    "statusMessage": "The question has the answers it needed.",
    "pollIntervalMs": 30000,
    "result": {
      "structuredContent": {
        "request_id": "req_01JD3F6Q8V2X4N7K9M5T1W0Y3Z",
        "status": "answered",
        "expires_at": "2026-11-17T17:12:04.512Z",
        "recipients": ["giulia@example.com"],
        "answers": [
          { "from": "giulia@example.com", "answers": { "ship": true }, "at": "2026-11-17T10:40:51.230Z" }
        ]
      },
      "content": [{ "type": "text", "text": "Request req_01JD3F6Q8V2X4N7K9M5T1W0Y3Z is answered. ..." }]
    }
  }
}
Some task fields are left out here for space.

A polling loop in a few lines

In a script, the loop is short. Wait the interval the server asks for, and stop when the task is no longer working. People answer in minutes or hours, so Guizzo asks for 30 seconds between calls.

ts
const MCP = "https://mcp.guizzo.ai/mcp";
const meta = {
  "io.modelcontextprotocol/protocolVersion": "2026-07-28",
  "io.modelcontextprotocol/clientInfo": { name: "release-bot", version: "1.0.0" },
  "io.modelcontextprotocol/clientCapabilities": { extensions: { "io.modelcontextprotocol/tasks": {} } },
};

async function rpc(id: number, method: string, name: string, params: object) {
  const res = await fetch(MCP, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GUIZZO_API_KEY}`,
      "Content-Type": "application/json",
      Accept: "application/json, text/event-stream",
      "MCP-Protocol-Version": "2026-07-28",
      "Mcp-Method": method,
      "Mcp-Name": name,
    },
    body: JSON.stringify({ jsonrpc: "2.0", id, method, params: { ...params, _meta: meta } }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.result;
}

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

let task = await rpc(1, "tools/call", "ask_person", {
  name: "ask_person",
  arguments: { to: ["giulia@example.com"], title: "Can we ship on Friday?", expires_in_hours: 8 },
});
for (let id = 2; task.status === "working"; id++) {
  await sleep(task.pollIntervalMs ?? 30_000);
  task = await rpc(id, "tasks/get", task.taskId, { taskId: task.taskId });
}

const answer = task.result?.structuredContent;
if (task.status === "completed" && answer?.status === "answered") {
  console.log(answer.answers);
} else {
  console.log(`No answer: ${task.statusMessage}`);
}

A tool call that fails, for example because the workspace is out of credits or none of the recipients can be reached, returns an ordinary error result with isError, not a task. Check for it before you start polling.

How a task ends

What happenedTask statusResult
The person answered (or enough people did, with mode all or quorum)completedstatus: "answered" with the answers
Nobody answered before expires_atcompletedstatus: "expired" and no answers
You called tasks/cancelcancelledNone. The question is closed

An expired question is a normal outcome, not an error: the result says nobody answered, and the agent decides what to do next, such as ask someone else or tell its user.

A question stays open 7 days unless the agent sets expires_in_hours, from 1 hour to 30 days. The task lives as long as the request, then for the plan's history period, which ttlMs gives in milliseconds from the moment it was created.

The fallback: no tasks, no problem

Not every client supports tasks yet. When a request doesn't declare the extension, ask_person returns at once with a request_id and the status pending, and the answers are read later with the inbox tool. The person answering sees no difference: the email and the web page are the same.

json
{
  "request_id": "req_01JD3F6Q8V2X4N7K9M5T1W0Y3Z",
  "status": "pending",
  "expires_at": "2026-11-17T17:12:04.512Z",
  "recipients": ["giulia@example.com"],
  "credits_charged": 1,
  "credits_remaining": 49,
  "not_delivered": [],
  "withheld": []
}

An agent in a chat should not loop on inbox while it waits. It is better to tell the user what it asked and check the inbox in a later turn, or when the user asks. The request lives in Guizzo, not in the chat, so the answer is there even in a new conversation.

Questions

Good to know.

Does polling with tasks/get use credits?

No. Only sending a question or an approval uses a credit. Reading a task or the inbox is free.

Does the agent have to keep running while it waits?

No. The request is stored in Guizzo, not in the agent. An agent can stop, start again later and call tasks/get with the same task id, or read the answer from its inbox.

Who can read a task?

Only the person who sent the request, in the same workspace, from any of their API keys or AI apps. Anyone else gets “Task not found”.

Which AI apps support MCP tasks?

Support is new and growing. We are testing each app during the beta and will list the results at guizzo.ai/agents. Apps without tasks still get every answer through the inbox.

Free beta

Give your agent someone to ask.

Sign up with your email and create your workspace. We open Guizzo to new teams a few at a time: if every place is taken, you join the queue and we write when yours is ready.

Free during the beta. We send a code to sign in, no password. If every place is taken you join the queue, and we write when yours is ready. Privacy policy