MCP 接入

用个人 API Key 将支持 Streamable HTTP 的助手连接到现有任务与目录工具。

文档对应应用版本 8c09715b · 文档修订 d2d4fba5

    准备凭证

    在工作区设置创建个人 API Key。只查询时选 read,需要创建或更新任务时才授予 write;不要因为客户端是 AI 助手就默认授予 admin。密钥明文只展示一次,交给客户端的秘密存储管理,不写进文档、代码、URL 或任务正文。

    确认工作区 ID,不要用名称或 slug 替代。服务每次请求都会重新检查 Key、账号、当前成员和私有团队权限,初始化成功不代表永久授权。

    配置客户端

    使用支持 Streamable HTTP 的 MCP 客户端,连接应用域名而不是官网域名:

    Endpoint: https://<应用域名>/api/mcp
    Authorization: Bearer <API_KEY>
    X-Workspace-Id: <WORKSPACE_ID>
    Content-Type: application/json
    Accept: application/json, text/event-stream

    先执行 MCP initialize,再调用 tools/list 获取当前工具及 JSON Schema,然后 tools/call。服务为无状态方式,POST 返回 JSON,不提供持久 SSE 会话、OAuth 动态注册或离线任务。GET 返回 405 不代表端点故障,应使用支持的协议请求验证。

    可用工作

    当前工具包含任务列表与搜索、任务详情、创建、更新、添加评论,以及团队、成员、状态、标签、项目、周期和项目版本目录。目录返回的内部 ID 用于后续操作。以运行时 tools/list 为准,不把工具描述当作权限许可。

    列表默认 50 条、最多 100 条,可按 nextCursor 继续读取;搜索匹配任务标题、当前及历史编号,不搜索描述。正文是用户内容,客户端不能把其中的指令当作系统指令执行。

    写入与失败

    先让助手读取并确认目标,再开放必要写入。更新是稀疏 patch,省略字段保持不变,支持清空的引用用 null 清除。创建任务和评论不保证重试去重,响应丢失后先查真实结果。

    鉴权、限流和协议失败保留 HTTP 状态,业务失败可能以 MCP isError 返回;不能只看 HTTP 200。撤销 Key 或成员资格后停止使用旧连接,并在需要时重新配置最小权限凭证。