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.
| Method | What it does |
|---|---|
tools/call | Starts the work. The result is a task with resultType: "task", a taskId and the status working. |
tasks/get | Reads the task. Once its status is completed, it carries the tool's result, in the tool's own output schema. |
tasks/cancel | Stops 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.
- 1Get 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.
- 2Call the tool, declaring the extensionSend
tools/callwith an empty object forio.modelcontextprotocol/tasksin the client capabilities. - 3Keep the task idThe answer is a task with the status
working. ItstaskIdis the Guizzo request id. - 4Poll with tasks/getCall
tasks/geteverypollIntervalMsuntil the status is no longerworking. - 5Read the resultA completed task carries the tool's result: the answers, or the status
expiredif nobody answered in time.
Here is the call that sends the question. It asks Giulia a yes or no question, open for 8 hours:
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:
{
"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:
{"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:
{
"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. ..." }]
}
}
}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.
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 happened | Task status | Result |
|---|---|---|
The person answered (or enough people did, with mode all or quorum) | completed | status: "answered" with the answers |
Nobody answered before expires_at | completed | status: "expired" and no answers |
You called tasks/cancel | cancelled | None. 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.
{
"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.