指南 / MCP 集成

把 MCP 客户端连接到 TO3D

使用线上 v2 HTTP 端点，在 MCP 客户端中发现 TO3D 工具。本指南记录端点和只读发现证据，不声称所有客户端都已测试，也不声称 MCP 能自动绑骨。

已于 2026 年 9 月 27 日核验

连接线上端点

在客户端配置 https://mcp.to3d.app/v2/mcp。支持 OAuth 的客户端可以完成 TO3D WorkOS AuthKit 登录；免认证工具可准备或检查请求，但生成仍需账户。

当前 14 个工具的接口使用 /v2/mcp 路径。
客户端请求 OAuth 作用域时，请求 openid 和 email。
登录会授权连接，但本身不会提交生成任务。

{
  "mcpServers": {
    "to3d": {
      "url": "https://mcp.to3d.app/v2/mcp"
    }
  }
}

执行 MCP 发现

客户端先调用 initialize，然后请求 tools/list 和 resources/list。这些是 live gate 使用的安全发现调用；本页不会调用生成工具。

initialize 建立协议和服务器信息。
tools/list 返回名称、schema 和安全方案。
resources/list 返回服务器公布的 widget 资源。

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"your-client","version":"1.0"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
{"jsonrpc":"2.0","id":3,"method":"resources/list","params":{}}

线上 14 个工具

当前 v2 响应把 OAuth 保护的账户/任务操作与免认证准备/诊断操作分开。客户端实现应以实际发现的名称和 schema 为准。

OAuth 表示客户端必须提供已连接账户的会话。
免认证表示工具可以在没有账户令牌时调用；这不代表生成免费。
只读提示描述工具注解，不能替代服务器的授权检查。

curl -fsS https://mcp.to3d.app/v2/mcp -H 'content-type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

live gate 中 tools/list 返回的工具
工具	访问	用途
`get_3d_credits`	OAuth	读取可用 credits
`estimate_3d_generation`	OAuth	估算生成 credits
`generate_3d`	OAuth	从图片生成
`image-to-3d`	无需认证	打开图片选择器
`process_image_url_to_3d`	无需认证	预览图片 URL
`prepare_3d_generation`	无需认证	准备选中的图片
`cancel_3d_generation`	无需认证	取消尚未提交的请求
`generate_3d_authenticated`	OAuth	启动已准备的生成
`get_authenticated_generation`	OAuth	检查生成任务
`create_3d_job_from_url`	OAuth	从 URL 恢复 3D 任务
`get_3d_job_status`	OAuth	检查任务状态
`get_3d_result`	OAuth	获取任务结果
`get_3d_status`	OAuth	检查任务
`report_widget_diagnostic`	无需认证	记录 widget 诊断

遵循任务流程

先准备图片，用户选择生成时完成认证，然后启动或恢复任务并读取状态与结果。保留每一步返回的 resumeKey、intentId、jobId 或 taskId，不要自行编造。

请求付费生成前先读取 credits 并获取估算。
使用 get_3d_job_status 或 get_3d_status 观察任务，服务器报告完成后再使用 get_3d_result。
当前端点没有 MCP humanoid 绑骨工具；独立绑骨任务请使用 REST Skin Tokens 流程。

prepare -> authenticate -> generate_3d_authenticated -> get_3d_job_status -> get_3d_result

客户端与能力边界

Web 工作台和 REST API 有各自的合同。MCP 客户端只应展示实际发现的工具和 schema，不要把其他路由的 OAuth、自动绑骨或兼容性说法复制过来。

较旧的 /mcp 路径是 existing-v1 兼容路由，不能证明这份 v2 工具列表。
此线上端点记录了 OAuth 支持；每个客户端的登录流程仍需单独验证。
本指南没有发起生成请求。

endpoint=https://mcp.to3d.app/v2/mcp
legacy=https://mcp.to3d.app/mcp