将 Server Workflow 连接为 MCP

每个可在 Server 运行的 projectType: "workflow" 项目都提供一个标准 Streamable HTTP MCP 入口。项目中的每个 entrypoint 对应一个 tool。Conversation 和 Kanban 不提供该入口。

在 Server Web 中打开 Workflow 项目详情的 MCP 页面，可以选择 draft、latest 或精确版本，复制 URL、Bearer header 模板和通用客户端 JSON，并查看当前 target 的 tool 目录。页面只显示 <YOUR_API_KEY>，不会读取或回显已保存密钥。

连接地址

https://workflow.example.com/api/workflows/<PROJECT_ID>/mcp?target=latest

通用 MCP 客户端配置：

{
  "mcpServers": {
    "workflow-11111111-1111-4111-8111-111111111111": {
      "url": "https://workflow.example.com/api/workflows/11111111-1111-4111-8111-111111111111/mcp?target=latest",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

MCP 只接受 Authorization: Bearer 中的账户 API Key 或服务器管理员 Key。浏览器 cookie session、Embed token、Webhook secret 和匿名请求都会被拒绝。账户 Key 仍需拥有项目运行权限和 runs.create；Server 在每次 HTTP 请求和每次 tool 调用前重新检查权限、项目运行门禁和队列限制。

Target 与会话

target	会话行为
`latest`	initialize 时解析为当时的精确在线版本，之后保持不变。
`1.2.3`	始终固定到该精确版本。
`draft`	固定到 initialize 时的源码 revision；草稿变化后旧会话拒绝继续调用。

初始化响应返回 Mcp-Session-Id。后续 POST、GET SSE 和 DELETE 必须继续携带该 header、相同 Bearer 凭据、项目和 target。会话不保存原始 Key，默认空闲 30 分钟后回收；过期、DELETE 或 Server 关闭会取消活动调用。跨凭据、跨项目或跨 target 复用会话返回 403。

连接建立后 tool 列表固定。项目或 draft 变化、发布新版本、entrypoint/params 变化后，断开并重新 initialize 才会得到新目录。

Tool 参数与文件

参数类型、required、默认值、静态 options、日期格式和未知字段拒绝规则与本地 MCP一致。服务端 file 参数使用 { "id": "..." }，multiple file 使用该对象数组。不要发送名称、MIME、路径、URL 或 Base64；Server 会按 ID 重新读取权威 metadata，并确认文件属于当前项目。

先通过现有文件 API 上传二进制内容：

curl --request POST \
  --header "Authorization: Bearer $WORKFLOW_API_KEY" \
  --header "Content-Type: application/octet-stream" \
  --data-binary @./spec.pdf \
  "https://workflow.example.com/api/workflows/$PROJECT_ID/files?fileName=spec.pdf&mimeType=application/pdf"

响应 data[0].id 用作 MCP tool 参数：

{
  "prompt": "检查规范",
  "document": {
    "id": "wf_0123456789abcdef"
  }
}

文件 ID 属于其它项目、不存在或 metadata 不是 server 文件时，调用以 MCP InvalidParams 失败。

执行、交互与审计

tool call 复用 Server 现有的 preflightRun、运行队列、持久化 run、related-project、Server 文件存储和 submitUserInput。每次调用都会创建可在运行日志中查询的 runId，并写入 MCP 会话、tool、恢复和 run 审计事件；日志来源显示为 mcp。

支持 form elicitation 的客户端可以在 waiting_for_input 或工具审批时继续同一 runId，并连续处理多次询问。不支持 elicitation、待输入包含 file 字段，或包含未配置静态 options 的任意数组字段时，tool 返回 interaction_required、runId 和字段摘要，不会自动批准。交互式多选字段需要配置静态 options，才能通过标准 MCP form 恢复。

成功的文本 content 与 structuredContent 都包含：

{
  "runId": "20260828-abcd",
  "status": "success",
  "entrypointId": "validate",
  "entrypointTitle": "Validate",
  "output": {}
}

运行失败、非零业务 errCode、取消或超时返回 isError: true 和精简 error。Server 不通过 MCP 返回完整 report、节点明细、stdout、stderr 或凭据。参数格式错误是 MCP InvalidParams；HTTP 鉴权失败使用 401/403；已进入 workflow 的失败是 MCP tool error。

协议方法、header 和 HTTP response 也会在文档站的 Server API 标签页中按 MCP operation 生成。

连接地址​

Target 与会话​

Tool 参数与文件​

执行、交互与审计​

连接地址

Target 与会话

Tool 参数与文件

执行、交互与审计