JADE REALMS / 开发者文档

MCP 接入指南

选择支持远程 Streamable HTTP 的客户端，新增下方地址，认证方式选择无需认证，然后发现工具。使用时不需要保持浏览器页面打开。

v1.0.0只读 · 无需 API 密钥OpenAPI JSON ↗

连接步骤

选择支持远程 Streamable HTTP 的客户端，新增下方地址，认证方式选择无需认证，然后发现工具。使用时不需要保持浏览器页面打开。

URL

https://3dmodelhub.io/mcp

在客户端新增远程 MCP 服务，URL 填入下方地址，传输方式选择 Streamable HTTP。
认证方式选择 None / 无需认证；当前公开服务没有 API 密钥和 OAuth 登录步骤。
完成工具发现后，应看到下方 7 个工具。先调用站点信息，再搜索模型，最后获取下载地址。

Transport: Streamable HTTP
Authentication: None
Server: jaderealms-public-assets

浏览器 WebMCP 是另一种接入；这里的 /mcp 使用标准远程协议。当前版本不包含 OAuth、个人已购素材库或私人订单查询。

MCP 工具

MCP 工具	REST API	必填
`jaderealms_get_site_info`	`GET /api/v1/site`	—
`jaderealms_search_models`	`GET /api/v1/models`	—
`jaderealms_get_model_details`	`GET /api/v1/models/{id}`	id
`jaderealms_list_scene_kits`	`GET /api/v1/kits`	—
`jaderealms_get_scene_kit_details`	`GET /api/v1/kits/{id}`	id
`jaderealms_get_usage_guidance`	`GET /api/v1/guidance`	topic
`jaderealms_get_model_downloads`	`GET /api/v1/models/{id}/downloads`	id

搜索 → 查看详情 → 下载

Tool arguments

{
  "name": "jaderealms_search_models",
  "arguments": {
    "q": "pine",
    "tested_engine": "godot",
    "max_triangles": 150000,
    "limit": 3,
    "locale": "zh"
  }
}

客户端代码示例

Setup

npm install --save-exact @modelcontextprotocol/sdk@1.32.1

JavaScript · Node.js 22+

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'asset-library-client', version: '1.0.0' });
try {
  await client.connect(new StreamableHTTPClientTransport(new URL("https://3dmodelhub.io/mcp")));
  console.log(await client.listTools());
  const result = await client.callTool({
    "name": "jaderealms_search_models",
    "arguments": {
      "q": "pine",
      "tested_engine": "godot",
      "max_triangles": 150000,
      "limit": 3,
      "locale": "zh"
    }
  });
  console.log(result.structuredContent);
} finally {
  await client.close();
}

协议请求示例

在浏览器地址栏直接打开这个地址会返回 405，因为服务接收的是 MCP POST 消息。请用下方协议示例或官方 SDK 客户端进行连接测试。

1 · initialize

curl --fail 'https://3dmodelhub.io/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"manual-check","version":"1.0.0"}}}'

2 · initialized

curl --fail 'https://3dmodelhub.io/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'

3 · tools/list

curl --fail 'https://3dmodelhub.io/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

4 · tools/call

curl --fail 'https://3dmodelhub.io/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"jaderealms_search_models","arguments":{"q":"pine","tested_engine":"godot","max_triangles":150000,"limit":3,"locale":"zh"}}}'

能力范围与兼容性

服务返回素材信息和文件地址，不能购买资源、读取私人账号或直接写入本地工程；聊天内交互式 3D 预览还取决于客户端界面支持。

只返回公开且已发布的目录事实。未知值保留 null；引擎导入检查只适用于记录中的 GLB 哈希，不等于性能认证。

元数据共用每 IP 每分钟 120 次的边缘保护，在 Cloudflare 各位置尽力执行；这不是免费文件的账号下载额度。

POST: initialize / notifications / tools/list / tools/call
GET / DELETE: 405 · OPTIONS: 204
JSON response · no persistent session ID · 32 KiB message limit
tools/call: content + structuredContent; isError=true on invalid arguments

错误与重试

HTTP / JSON-RPC	说明
405	地址栏使用 GET；请通过 MCP 客户端或下方 POST 示例连接。
406	Accept 需要同时包含 application/json 和 text/event-stream。
415	发送 JSON，Content-Type 使用 application/json。
403	浏览器 Origin 不在允许列表。服务默认允许本站及已配置的 ChatGPT、Claude、Cursor 来源；其他浏览器客户端需由站点管理员配置 MCP_ALLOWED_ORIGINS。
413	单条请求体不能超过 32 KiB；不接受批量消息。
429	等待 Retry-After 指定的秒数后重试。
JSON-RPC / tools/call	先检查 JSON-RPC error；工具返回 result.isError=true 时，检查 result.structuredContent 或文本中的错误和参数，不要把它当作成功结果。