MCP 接入指南

Matrees 提供 Model Context Protocol (MCP) 服务，供 Claude Code、Cursor、OpenClaw 等外部 Agent 在授权范围内检索世界观、创建/提交提案。

接入分两步：创建 MCP Key（身份认证）与 为世界开通 MCP 服务（按世界计费准入）。两步都完成后，Agent 方可调用该世界的 MCP 工具。

谁可以使用

仅世界创建者/所有者或世界管理员可使用 MCP（含公会会长/副会长）。
审核员、共创者、普通提案者请继续使用 Web 提案表单；其账号无法调用 MCP 写操作。

接入流程

1. 创建 MCP Key

登录 Matrees → 个人中心 → 账号安全 → MCP 接入
点击「创建 Key」，填写备注名
立即复制完整 Key（形如 mtk_…），关闭后无法再次查看
在 MCP 接入页可查看「配置示例」，按 Cursor / Claude Code / OpenClaw 等客户端粘贴 JSON

MCP Key 仅可用于 MCP 端点，不能替代登录 Token 调用普通 Web API。Key 只负责身份认证，不再配置 read/write 范围或世界白名单。

2. 为世界开通 MCP 服务

外部 Agent 读写某个世界前，该世界须已开通 MCP 服务：

进入目标世界的 世界设置（世界管理弹窗）→ MCP 服务 Tab
使用 MCP 服务卡 开通或延长服务（默认 30 天/张，多张可叠加）
页面显示「已开通 · 有效期至 …」后，该世界才会出现在 listAccessibleWorlds 结果中

未开通或已过期时，带 worldId 的工具调用会返回 MCP_SERVICE_INACTIVE。语义检索（semanticSearchWorld）会消耗模型 Token，请合理开通服务期。

服务卡可在 兑换中心 获取；世界设置页会显示当前持有的可用张数。

连接参数

项	值
Endpoint	`POST https://www.matrees.cn/mt/ai/mcp`
认证 Header	`Authorization: Bearer mtk_xxxxxxxx`
Content-Type	`application/json`

协议为 JSON-RPC 2.0（Streamable HTTP），与 n8n mcpClientTool 相同。

工具能力概览（21 个）

只读 / 检索

工具	说明
`listAccessibleWorlds`	列出已开通 MCP 服务、且您为创建者/管理员的世界
`keywordSearchWorld`	关键词搜索（设定/事件/作品/地图/章节等）
`semanticSearchWorld`	语义向量检索
`getDefinition` / `getEvent` / `getConcept`	实体详情
`getDefinitionTree` / `getCalendars` / `getWorldOverview`	结构与世界概览
`getProposalStatus` / `listMyProposals`	提案状态与列表

写 / 提案草稿

工具	说明
`createDefinitionProposal` / `updateDefinitionProposal` / `deleteDefinitionProposal`	设定/设定集提案
`createEventProposal` / `updateEventProposal` / `deleteEventProposal`	事件提案
`updateConceptProposal`	世界概念提案

写操作创建的是提案草稿，须通过生命周期工具提交审核后才可能成为正式内容；无直接修改正式版的工具。

设定集展示：createDefinitionProposal / updateDefinitionProposal 支持 showInList（仅设定集有效），控制是否在侧栏「设定列表」中展示；创建设定集时默认为不展示。

提案生命周期

工具	说明
`submitProposal`	提交审核（返回是否自动通过）
`revokeProposal`	撤回审核中的提案
`discardProposal`	丢弃草稿

提交后若未自动审核通过，可能存在版本冲突，请前往 Web 提案中心手动处理；MCP 不提供合并审核。

Claude Code 配置示例

在 MCP 配置中增加 HTTP 类型服务器（具体字段名以客户端文档为准）：

json

{
  "mcpServers": {
    "matrees": {
      "url": "https://www.matrees.cn/mt/ai/mcp",
      "headers": {
        "Authorization": "Bearer mtk_你的Key"
      }
    }
  }
}

Cursor、OpenClaw 等客户端的配置字段名可能略有不同，请以 MCP 接入页「配置示例」为准。

安全建议

为每个客户端/环境单独创建 Key，便于吊销
仅为需要 Agent 接入的世界开通 MCP 服务，避免不必要的 Token 消耗
Key 泄露后请在「MCP 接入」页立即吊销
默认限流约 60 次/分钟（按 Key 或用户计），频繁调用请适当间隔

MCP 接入指南 ​

谁可以使用 ​

接入流程 ​

1. 创建 MCP Key ​

2. 为世界开通 MCP 服务 ​

连接参数 ​

工具能力概览（21 个） ​

只读 / 检索 ​

写 / 提案草稿 ​

提案生命周期 ​

Claude Code 配置示例 ​

安全建议 ​

相关文档 ​