MCP 接入指南

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

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

谁可以使用

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

接入流程

1. 创建 MCP Key

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

MCP Key 仅可用于 MCP 端点，不能替代登录 Token 调用普通 Web API。Key 只负责身份认证，不再配置 read/write 范围或世界白名单；tools/list 默认暴露全部工具，实际调用仍受世界权限与 MCP 服务卡约束。

2. 为世界开通 MCP 服务

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

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

未开通或已过期时，带 worldId 的工具调用会返回 MCP_SERVICE_INACTIVE。语义检索（searchWorld(mode=semantic)）会消耗模型 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 相同。

工具能力概览（30 个语义入口）

旧版按实体或操作拆分的工具，已合并为按语义组织的入口。请通过 operate、mode、entityType、proposalType 等参数区分具体操作；长流程说明可从 MCP resources/read 读取。

只读检索（6）

工具	说明
listAccessibleWorlds	列出已开通 MCP 服务、且您为创建者/管理员的世界
searchWorld	世界检索；mode=keyword 为关键词搜索，mode=semantic 为语义检索
getEntity	读取设定、事件或世界概念；用 entityType 区分
getWorldContext	读取世界概览、历法或设定集树；用 part 区分
getContentBlocks	分段或按 blockId 读取实体正文
listMyProposals	查询我的提案，传 proposalId 时查询单条状态

世界提案（5）

工具	说明
writeDefinitionProposal	创建或更新设定/设定集提案；operate=create | update
writeEventProposal	创建或更新事件提案；operate=create | update
writeConceptProposal	更新世界概念提案
deleteEntityProposal	为设定或事件创建删除提案；用 entityType 区分
manageProposal	提交、撤回或丢弃提案；operate=submit | revoke | discard

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

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

记忆（4）

工具	说明
getMemory	语义召回用户/世界记忆（可带 query）；返回条目与画像/技能，不返回旧 JSON 契约
writeMemory	写入提炼短句；用 mode 区分。写入后不立即对召回可见
recordMemoryAtom	记录可追溯的稳定偏好或规则证据
getRecentChatMessages	按需补读近期会话消息以恢复上下文

审核（3）

工具	说明
listPendingProposals	列出世界内待审核提案
getProposalDiff	获取提案版与正式版的差异
auditProposal	通过、拒绝或选择性合并通过提案

小说（8）

工具	说明
getWork / listNovelStructure	读取作品元数据、分卷与章节目录
getChapter / listMySeeds	读取章节、列出可用作品种子
writeWorkProposal	创建、更新或删除作品提案；用 operate 区分
writeChapterProposal	创建、更新或删除章节提案；用 operate 区分
manageVolume	创建、更新或删除分卷；用 operate 区分
sortNovelStructure	调整分卷或章节完整顺序；用 target 区分

关联（4）

工具	说明
listRelationEnums	列出官方与自定义关联类型
listItemRelations	列出设定或事件的正式关联边
writeRelationProposal	创建或更新关联关系提案；用 operate 区分
manageRelationEnum	查询配额、创建、更新、查询用法或删除自定义关联类型；用 operate 区分

tools/list 默认返回全部 30 个语义入口；能否真正调用仍以世界权限、MCP 服务卡与审核门禁为准。

Claude Code 配置示例

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

{
  "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 或用户计），频繁调用请适当间隔

相关文档

• 账号与安全 — 个人资料与其它安全设置
• 提交提案 — Web 端提案与审核流程
• 世界概览 — 世界设置与管理入口说明