鸭梨公共文档

主题

任务 ​

协议版本: 2025-11-25

NOTE

任务在 MCP 规范的 2025-11-25 版本中引入，目前被视为实验性功能。任务的设计和行为可能在未来的协议版本中发生变化。

模型上下文协议（MCP）允许请求者——可以是客户端或服务器，取决于通信方向——用任务增强其请求。任务是携带关于它们包装的请求的底层执行状态信息的持久状态机，旨在用于请求者轮询和延迟结果检索。每个任务由接收者生成的任务 ID 唯一标识。

任务对于表示昂贵的计算和批处理请求非常有用，并且与外部作业 API 无缝集成。

1 定义 ​

任务将各方表示为"请求者"或"接收者"，定义如下：

  • 请求者：任务增强请求的发送者。这可以是客户端或服务器——任何一方都可以创建任务。
  • 接收者：任务增强请求的接收者，以及执行任务的实体。这可以是客户端或服务器——任何一方都可以接收和执行任务。

2 用户交互模型 ​

任务被设计为请求者驱动的——请求者负责用任务增强请求并轮询这些任务的结果；同时，接收者严格控制哪些请求（如果有）支持基于任务的执行，并管理这些任务的生命周期。

这种请求者驱动的方法确保了确定性的响应处理，并支持复杂的模式，如分派并发请求，只有请求者有足够的上下文来编排这些。

实现可以通过任何适合其需求的界面模式公开任务——协议本身不强制要求任何特定的用户交互模型。

3 能力 ​

支持任务增强请求的服务器和客户端必须在初始化期间声明 tasks 能力。tasks 能力按请求类别结构化，布尔属性指示哪些特定请求类型支持任务增强。

3.1 服务器能力 ​

服务器声明它们是否支持任务，如果支持，哪些服务器端请求可以用任务增强。

能力描述
tasks.list服务器支持 tasks/list 操作
tasks.cancel服务器支持 tasks/cancel 操作
tasks.requests.tools.call服务器支持任务增强的 tools/call 请求
json
{
  "capabilities": {
    "tasks": {
      "list": {},
      "cancel": {},
      "requests": {
        "tools": {
          "call": {}
        }
      }
    }
  }
}

3.2 客户端能力 ​

客户端声明它们是否支持任务，如果支持，哪些客户端端请求可以用任务增强。

能力描述
tasks.list客户端支持 tasks/list 操作
tasks.cancel客户端支持 tasks/cancel 操作
tasks.requests.sampling.createMessage客户端支持任务增强的 sampling/createMessage 请求
tasks.requests.elicitation.create客户端支持任务增强的 elicitation/create 请求
json
{
  "capabilities": {
    "tasks": {
      "list": {},
      "cancel": {},
      "requests": {
        "sampling": {
          "createMessage": {}
        },
        "elicitation": {
          "create": {}
        }
      }
    }
  }
}

3.3 能力协商 ​

在初始化阶段，双方交换其 tasks 能力以确定哪些操作支持基于任务的执行。请求者应该仅在接收者声明了相应能力时才用任务增强请求。

3.4 工具级协商 ​

工具调用为任务增强的目的得到特别考虑。在 tools/list 的结果中，工具通过 execution.taskSupport 声明对任务的支持，如果存在，其值可以是 "required"、"optional" 或 "forbidden"。

4 协议消息 ​

4.1 创建任务 ​

任务增强的请求遵循与正常请求不同的两阶段响应模式：

  • 正常请求：服务器处理请求并直接返回实际操作结果。
  • 任务增强请求：服务器接受请求并立即返回包含任务数据的 CreateTaskResult。实际操作结果在任务完成后通过 tasks/result 变得可用。

请求：

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "New York"
    },
    "task": {
      "ttl": 60000
    }
  }
}

响应：

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "task": {
      "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
      "status": "working",
      "statusMessage": "The operation is now in progress.",
      "createdAt": "2025-11-25T10:30:00Z",
      "lastUpdatedAt": "2025-11-25T10:40:00Z",
      "ttl": 60000,
      "pollInterval": 5000
    }
  }
}

4.2 获取任务 ​

请求者通过发送 tasks/get 请求轮询任务完成情况。

请求：

json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tasks/get",
  "params": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
  }
}

响应：

json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "status": "working",
    "statusMessage": "The operation is now in progress.",
    "createdAt": "2025-11-25T10:30:00Z",
    "lastUpdatedAt": "2025-11-25T10:40:00Z",
    "ttl": 30000,
    "pollInterval": 5000
  }
}

4.3 检索任务结果 ​

任务完成后，通过 tasks/result 检索操作结果。

请求：

json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tasks/result",
  "params": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
  }
}

响应：

json
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
      }
    ],
    "isError": false,
    "_meta": {
      "io.modelcontextprotocol/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

4.4 任务状态通知 ​

当任务状态更改时，接收者可以发送 notifications/tasks/status 通知。

通知：

json
{
  "jsonrpc": "2.0",
  "method": "notifications/tasks/status",
  "params": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "status": "completed",
    "createdAt": "2025-11-25T10:30:00Z",
    "lastUpdatedAt": "2025-11-25T10:50:00Z",
    "ttl": 60000,
    "pollInterval": 5000
  }
}

4.5 列出任务 ​

请求：

json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tasks/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

4.6 取消任务 ​

请求：

json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tasks/cancel",
  "params": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
  }
}

5 消息流程 ​

5.1 基本任务流程 ​

5.2 带通知的任务流程 ​

6 数据类型 ​

6.1 Task ​

任务表示请求的执行状态。任务状态包括：

  • taskId：任务的唯一标识符
  • status：任务执行的当前状态
  • statusMessage：描述当前状态的可选人类可读消息
  • createdAt：创建任务时的 ISO 8601 时间戳
  • ttl：从创建到任务可能被删除的时间（毫秒）
  • pollInterval：状态检查之间建议的时间（毫秒）
  • lastUpdatedAt：任务状态最后更新时的 ISO 8601 时间戳

6.2 任务状态 ​

任务可以处于以下状态之一：

状态描述
working请求当前正在处理中
input_required接收者需要来自请求者的输入
completed请求成功完成，结果可用
failed关联的请求未成功完成
cancelled请求在完成之前被取消

7 安全注意事项 ​

7.1 任务隔离和访问控制 ​

任务 ID 是访问任务状态和结果的主要机制。当提供授权上下文时，接收者必须将任务绑定到该上下文。

7.2 资源管理 ​

接收者应该：

  • 对每个请求者的并发任务施加限制
  • 强制执行最大 ttl 持续时间以防止无限期的资源保留
  • 及时清理过期任务以释放资源

7.3 审计和日志记录 ​

接收者应该：

  • 记录任务创建、完成和检索事件以供审计
  • 在日志中包含授权上下文（如果可用）
  • 监控可疑模式