接入指南 · 魔图

接入 Agent 工具

1
打开 MCP 设置
右上角齿轮 → 左侧 Tools & MCP → 点 Add。也可以跳过界面，直接在项目根目录新建 .cursor/mcp.json，效果完全一样。
截图占位
Cursor · Cursor 设置 → Tools & MCP 页面
替换方式：把此处换成 <img src="..." />
2
粘贴这段配置
下面的配置里已经自动填好你的服务地址和令牌，直接复制粘贴保存即可。想对所有项目生效就写到 ~/.cursor/mcp.json。
.cursor/mcp.json
```
// .cursor/mcp.json（项目级）
{
  "mcpServers": {
    "motu": {
      "url": "https://omutu.cn/mcp",
      "headers": {
        "Authorization": "Bearer <你的令牌>"
      }
    }
  }
}
```
截图占位
Cursor · .cursor/mcp.json 文件内容
替换方式：把此处换成 <img src="..." />
3
确认出现绿点
回到 Tools & MCP，motu 前面的小圆点是绿色，就说明连上了。红色点一下右侧的刷新按钮。
注意：看到 9 tools 就对了；如果显示 0 tools，先检查令牌有没有带 Bearer 前缀。
截图占位
Cursor · Tools & MCP 列表里 motu 显示绿点
替换方式：把此处换成 <img src="..." />
4
在 Composer 里说一句话
⌘/Ctrl + I 打开 Composer，直接用中文说，不需要 @ 任何文件或工具，Agent 会自己判断该调用 create_diagram。
截图占位
Cursor · 在 AI 客户端里输入「读一下调用链，画张架构图」
替换方式：把此处换成 <img src="..." />

调用

接好了，然后呢

工具会自动出现在你的 AI 客户端里。你不需要记住它们的名字，但也值得知道有哪几把。

可用的工具

get_playbook取绘图剧本：不带参数=索引与判型，带 kind=该图型分册
create_diagram建图并自动布局，返回可编辑链接与公开分享链接
update_diagram按 id 增量改图，只发变化的部分
beautify_diagram原地美化：配色、尺寸、正交连线（不改内容）
list_diagrams列出最近 200 张图纸的摘要
get_diagram取回完整 JSON，含你在浏览器里的手改
generate_icon让模型画一个图标并存入图标库
save_icon存入你自己写的 SVG 图标
list_icons列出内置图标名与自定义图标

其中 3 个图标工具（generate_icon、save_icon、list_icons）让 AI 缺图标时自己画一个，不用将就。删除类工具（删图 / 删图标）不开放给模型，只能在魔图网页里操作。

三句话试试水

直接复制到对话里，看它会不会画图。

读一下当前项目的模块依赖关系，画一张架构图

把 docs/design.md 里的下单流程整理成流程图

读一下我刚改的那张图，把支付环节拆细一点

推荐的协作方式

1.AI 读代码 → 出图，给你一条链接

2.你在浏览器里手动调整细节

3.让 AI 用 get_diagram 读回你的修改再继续

4.图乱了就让它跑一次 beautify_diagram

排查

出问题了，先查这张表

九成的接入问题都集中在前四条：位置、格式、Bearer 前缀、地址结尾。

现象大概率是怎么办

客户端里根本看不到魔图的工具

配置没被读到，或读到了但有语法错误

确认文件放对位置；JSON 里不能有注释、不能有尾随逗号、引号必须是英文半角。

报 401 / Unauthorized

令牌没填、填错，或格式不对

必须是 "Bearer 空格令牌"。Bearer 后面有且只有一个空格，令牌前后不要留空格或换行。

报 404

服务地址不对

地址结尾是 /mcp，不是 /api/mcp 也不是根域名。用本页顶部的「服务端点」为准。

工具在，但一调用就报错

令牌被重新生成过，旧令牌已失效

回到本页第 1 步复制当前令牌，更新客户端配置。

返回 -32003

触发了限流

每分钟 120 次调用、generate_icon 每分钟 10 次。等一分钟再试，正常对话不会碰到。

返回 -32002

服务端存储临时不可用

数据库连接抖动，稍后重试即可。持续出现请反馈。

图生成了，但画得乱七八糟

布局引擎没排好，或者节点关系描述不清

让 AI 跑一次 beautify_diagram 重排；或者把话说具体一点，比如「分三层：接入层、服务层、存储层」。

我在页面上的手动修改被 AI 覆盖了

AI 凭记忆重写了整张图，没读你当前的画布

让它先读再改：「先 get_diagram 读一下我现在的图，再在右边加一个风控节点」。

还是不行？把客户端的 MCP 日志和报错原文发给我们，比截图更快定位。

安全

令牌等同密码

持有令牌就能以你的身份创建和修改图纸。这几条请务必看一眼。

别提交到公开仓库

项目级的 .cursor/mcp.json、.trae/mcp.json 会被 git 跟踪。要么用全局配置，要么把目录写进 .gitignore。

泄露了立刻重新生成

第 1 步里的「重新生成」会让旧令牌立即失效，再去更新所有客户端配置。

一个令牌走天下

所有客户端共用同一个令牌就行，方便统一轮换。

AI 删不了你的图

MCP 不开放删除类工具（图纸 / 图标都不给），模型只能建图和改图；要删请到魔图网页里自己动手。

配好了？回去画第一张图

在 AI 里说一句话，拿一条链接，打开就能改。

回首页我的项目

打开 MCP 设置

粘贴这段配置

确认出现绿点

在 Composer 里说一句话

接好了，然后呢

出问题了，先查这张表

令牌等同密码