MCP 工具接入指南

本文档介绍如何在支持 MCP Streamable HTTP 协议的常见客户端（如 Cursor、Claude Desktop）中接入 Hitem3D 的 3D 生成能力。

一、场景与功能概览

典型场景：
- 在 Cursor、Claude Desktop 等 MCP 客户端中，通过自然语言调用 Hitem3D，完成「图生 3D」任务；
- Agent 自动轮询任务状态，在生成完成后获取 3D 模型下载地址与封面图。
接入方式：
- 通过 MCP Streamable HTTP 协议接入；

二、基础配置

1. MCP 服务地址

在线正式服务地址为：

text

https://mcp.hitem3d.ai/mcp

在 Cursor、Claude Desktop 等 MCP 客户端中，将 endpoint / url 指向上述地址即可。

2. 鉴权方式

Hitem3D MCP 服务通过 Hitem3D OpenAPI 调用后端，因此需要在 MCP 客户端中配置 Basic Auth：

在 MCP 客户端（如 Cursor 的 .cursor/mcp.json 配置文件）中，为 https://mcp.hitem3d.ai/mcp 配置请求头：
- Authorization: Basic base64(client_id:client_secret)
其中 base64(client_id:client_secret) 为将 client_id:client_secret 字符串进行 Base64 编码后的结果。

一个完整的 Cursor 配置示例如下（位于 ~/.cursor/mcp.json）：

json

{
  "mcpServers": {
    "hitem3d-mcp-server": {
      "url": "https://mcp.hitem3d.ai/mcp",
      "headers": {
        "Authorization": "Basic base64(client_id:client_secret)"
      }
    }
  }
}

注意：
目前只支持 Basic 方式鉴权；
请妥善保管 client_id 和 client_secret，不要泄露给非受信端。

三、工具行为概览

Hitem3D MCP 服务会自动通过 MCP 协议向客户端暴露可用工具（如提交任务、查询任务状态等）。
大多数 MCP 客户端（包括 Cursor、Claude Desktop）会在连接成功后自动列出这些工具，Agent 也能根据描述自行选择合适的工具组合完成工作。

四、在 MCP 客户端中生成 3D 的示例

当你在 MCP 客户端中完成以下配置后：

MCP 服务器地址：https://mcp.hitem3d.ai/mcp
在客户端里为该服务器配置好 Authorization 头（Bearer 或 Basic）

就可以直接在对话中用自然语言生成 3D。例如：

在 Cursor 中：
- 打开 MCP 面板，确认已连接 hitem3d（名称以你配置为准）；
- 在对话中输入：
  帮我把这张图片生成一个 3D 模型，使用最高质量的分辨率，并在完成后给我 3D 模型下载链接和封面图链接。image_url是：https://example.com/my-model.png
在 Claude Desktop 中：
- 在「工具 / MCP」里确保已经添加并启用 https://mcp.hitem3d.ai/mcp；
- 在对话中输入：
  我有一张角色图片，image_url是：https://example.com/character.jpg，请用 Hitem3D 生成一个带纹理的 3D 模型，并告诉我生成进度，完成后输出模型下载地址和封面图地址。

在这些对话指令下，客户端会自动选择合适的 Hitem3D MCP 工具（如「提交生成任务」「轮询任务状态」），完成从 2D 图片到 3D 模型的整套流程。

五、最佳实践与建议

安全管理：
- 建议在 MCP 客户端的统一配置中设置 Authorization: Basic base64(client_id:client_secret)，不要在对话中直接暴露密钥；
- 避免在公共场景（如共享录屏、截图）中展示完整的 Basic 凭证。
对话提示建议：
- 通过自然语言说明你的需求，例如提供图片地址、期望的模型质量或分辨率，以及是否需要带纹理等，Agent 会自动选择合适的工具组合；
- 对于长时间任务，可以在提示中要求「定期报告进度」或「任务完成后再返回下载地址」。
错误处理：
- 当生成失败时，建议查看 MCP 返回的文本信息（如图片无法下载、鉴权失败等），并根据提示修正图片 URL 或重新配置凭证后重试。

MCP 工具接入指南 ​

一、场景与功能概览 ​

二、基础配置 ​

1. MCP 服务地址 ​

2. 鉴权方式 ​

三、工具行为概览 ​

四、在 MCP 客户端中生成 3D 的示例 ​

五、最佳实践与建议 ​