墨刀 AI MCP 可以把生成原型、继续修改任务、读取已有原型等能力接入 Codex、Claude Code 和其他支持 MCP 的工具。第一次使用，先获取个人空间令牌，连接远程 HTTP 服务，再查询账号验证身份。之后按任务选择入口：从零做页面用 HTML 生成；修改已完成内容用原任务 ID 继续；接手已有设计则先查项目、读画布，再整理说明。
这三条路径的输入不同，不需要每次都重新生成。先打开墨刀 AI MCP 官方接入页取得当前地址与工具列表，再用下面的配置和指令完成第一次调用。需要处理大量本地文件时，也可以先在墨刀 AI 客户端中整理材料，再把明确的需求交给原型任务。
先选对入口：生成新内容、继续任务，还是读取原型
MCP 是当前 AI 工具调用墨刀能力的连接方式。接入后，Codex 等客户端理解你的要求，并选择相应工具；墨刀执行生成、查询、导入或读取操作。把目的说清楚，比记住所有工具名称更有用。
| 你现在要做什么 | 从哪里开始 | 得到什么 |
|---|---|---|
| 从一份需求做页面 | 选择 HTML 生成，完成后查询任务 | 预览与生成产物，需要时导入可编辑原型 |
| 给昨天的方案补一个规则 | 查找原任务，确认状态，再继续任务 | 同一任务中的修改结果 |
| 接手已经在墨刀中的设计 | 查找本人创建的原型，读取目录与画布 | 页面结构、文字、组件和已表达的交互 |
| 从业务系统集成生成能力 | 评估墨刀 AI API | 面向程序的请求与响应处理 |
如果还不清楚客户端与服务之间的关系，可先读MCP 是什么。接下来的步骤以个人令牌连接为主；OAuth 需要客户端和服务端的授权流程兼容，并非所有工具都能直接完成。
第一步：获取令牌，配置远程服务
登录墨刀 AI，从头像菜单进入“令牌设置”，创建个人空间令牌。配置使用当前服务地址 https://modao.cc/agent-py/ai/mcp，传输方式为 Streamable HTTP，请求头名称是 modao-token。它不是普通网页地址，不需要在浏览器里打开后寻找编辑器。
Codex：使用 config.toml 和环境变量
打开用户级 ~/.codex/config.toml；Windows 通常对应用户目录下的 .codex/config.toml。在启动 Codex 的环境中设置 MODAO_TOKEN，然后加入：
[mcp_servers.modao]
url = "https://modao.cc/agent-py/ai/mcp"
env_http_headers = { "modao-token" = "MODAO_TOKEN" }这里填写的是环境变量名称，不是真实令牌。保存后重启 Codex，运行 codex mcp list 检查服务是否已注册，再在会话中检查连接状态。终端里临时设置的变量不会自动传给已经运行的桌面应用；遇到未授权提示，先确认当前进程能读取该变量。具体配置字段可对照 OpenAI MCP 配置文档。
其他客户端：按各自入口填写同一地址
WorkBuddy、Qoder、TRAE 等客户端的配置入口不同，不能把 Codex 的 TOML 直接粘进要求 JSON 的窗口。通用的关键项是服务地址、HTTP 传输与自定义请求头。例如支持以下结构的客户端可参考：
{
"mcpServers": {
"modao": {
"url": "https://modao.cc/agent-py/ai/mcp",
"headers": { "modao-token": "YOUR_MODAO_TOKEN" }
}
}
}YOUR_MODAO_TOKEN 只是占位值；部分客户端还需要声明 HTTP 类型，按其配置要求填写。Claude Code、WorkBuddy、Qoder 与 TRAE 的当前菜单和完整示例，可在文首官方接入页选择对应标签查看。真实令牌只保存在可信的本机配置中，不提交到仓库、截图或共享文档；停用或泄露时，在令牌设置中删除并重新创建。
第二步：先确认账号，再发起生成
服务显示已连接之后，先让 AI 调用 get_account_status 查询当前账号、默认个人空间与积分状态。这是只读查询，适合检查“连的是谁的账号”，不会创建生成任务。账号身份不对时，先更换授权，不要继续生成后再找作品。
查询当前墨刀账号与默认个人空间，告诉我连接是否成功、可用权益是什么。先不要创建生成任务，也不要输出令牌。
当前官方目录提供 17 个工具。如果旧连接只显示少量生成工具，先刷新工具列表或重启客户端。连接注册成功、身份查询成功、生成产物完成是三个不同结果：前一步正常，不代表后一步已经完成。
第三步：从明确需求生成 HTML 原型、应用或 PRD
保留一种清楚的交付目标，能够减少来回修改。需要页面结构和可点击方案时选 HTML；明确要 React 或 Vue 工程起点时指定相应技术栈；需求规则还没有整理清楚时，可以先生成 PRD。
| 产物 | 工具 | 适合的任务 |
|---|---|---|
| HTML 原型 | generate_html | 验证页面、布局和主要操作，随后导入墨刀继续设计 |
| React 应用 | generate_react | 明确采用 React 的应用或交互页面 |
| Vue 应用 | generate_vue | 明确采用 Vue/Vue3 的应用或交互页面 |
| 需求文档 | generate_prd | 整理目标、业务规则、流程和验收要求 |
| 图片 | generate_image | 需要以图片为最终产物的海报或配图 |
| 未明确类型的内容 | generate | 无法归入前面类型的生成任务 |
以原文中的“用户访谈预约”为例，一条可用的生成要求需要交代用户、页面、规则、异常和输出：
使用墨刀 AI 生成移动端用户访谈预约的 HTML 原型。
用户：收到研究邀请、准备选择访谈时间的注册用户。
页面：场次选择、信息填写、预约确认。
规则：每人仅能保留一个有效预约；已满场次不可选择。
状态：手机号格式错误、场次已满、重复预约、提交失败、预约成功。
失败后保留已填信息，允许修改或重试。
输出预览入口与任务 ID。不要添加支付或社区功能。工具返回任务 ID 后，把它留在当前工作记录中。若状态仍是 running，使用 get_task_result 查询同一个任务；不要把暂未完成理解为没有开始，也不要连续提交相同需求。只有结果明确完成后，才进入预览与导入。
已有内容需要修改：继续原任务，不再从头做一遍
预约原型已经生成，后来新增“用户可以改期，但开始前一天不允许改期”。此时真正需要的是保留原有页面并补规则。先用 list_recent_tasks 在默认个人空间查找原任务，核对标题、时间与任务 ID，再查询状态。
找到最近的“用户访谈预约”任务，先返回匹配项让我确认。
确认目标后，查询任务状态。
如果已完成，在这个任务上增加“改期”功能：
预约开始前不足24小时不允许改期，并说明原因；
允许改期时保留姓名和手机号，只重新选择场次；
改期失败时保留原预约，给出重试入口。
保留原有页面风格与其他规则，不新建另一套项目。continue_task 需要任务 ID。已完成任务要提供新的修改要求；失败或暂停任务可以继续；仍在运行的任务先查询状态，不再次继续。近期任务查询与原型查询是两套不同入口：前者找 AI 任务，后者找墨刀原型项目，不能把两种 ID 混用。
如果明确不想继续生成，可要求使用 paused_task 暂停指定任务。发出请求后仍要核对服务端状态，不能只凭“已发送暂停请求”判断已经停止。需要下载产物时，download_generated_content 返回下载入口，应在已登录对应账号的浏览器打开。
已经有墨刀原型：先读目录，再读取目标画布
接手存量项目时，不必让 AI 重画。使用 list_created_prototypes 查找当前账号本人创建的 proto2 原型，支持按项目、空间或组织名称筛选。它可以跨本人所属空间查询，但不等于列出所有别人分享给你的项目。
- 核对项目名称与所属空间，取得实际返回的
project_cid。 - 用
get_proto_details读取页面与画布目录。 - 从目录中选择真实
target_key，继续读取目标页面或画布。 - 需要核对视觉时，取得实际
canvas_key，用export_proto_to_png导出指定画布。
查找我创建的“用户访谈预约”原型。先列出匹配项目和画布目录，确认后读取预约确认页，整理文字、组件和已配置的交互。未提供的业务规则列为待确认，不修改原型。随后导出该画布 PNG，并告诉我链接有效期。
详情读取是只读操作，不会直接修改画布，也不会自动把项目转换成生产代码。PNG 导出每次针对指定画布，返回图片链接与有效期；交接时及时保存允许使用的图像，避免长期依赖临时链接。完整的接手过程可以继续看Codex 读取已有原型与整理交互说明的实操。
把 HTML 导入为可编辑原型，怎样避免走错路
import_to_proto 支持 HTML 文本、多页面 HTML 列表，以及本人已完成任务的 ID 或链接。新原型创建在默认个人空间；不能直接传外部网页 URL、React/Vue 工程，也不能用它任意指定另一个目标空间。
如果代码由 Codex 在本地生成，先检查页面能否独立展示、图片与样式是否可用，再把实际 HTML 内容交给导入工具。不要只给一个本机文件路径并假定远程服务能访问你的磁盘。多页导入后核对页面名称、图层、文本与跳转；HTML 能在浏览器运行，也不代表其中全部脚本与业务逻辑都已转成墨刀交互。具体文件处理和前后对照见多页面 HTML 导入再编辑教程。
另一个容易混淆的工具是 export_proto_to_html：它为与本人已有任务关联的可编辑原型提供 HTML 下载链接，需要完整原型项目地址。它是只读导出，不发起新生成，也不应理解为任何可访问项目都能任意导出。
遇到问题，按连接、任务和原型分别排查
| 现象 | 先核对 | 下一步 |
|---|---|---|
| 服务无法连接 | 地址完整、使用 HTTP、网络可达 | 按官方当前配置恢复连接，避免沿用旧 stdio 包 |
| 提示未授权 | 令牌有效，请求头名称正确，进程可读环境变量 | 修正本机配置后重新查询账号 |
| 能连接但没有新工具 | 工具列表是否缓存 | 刷新或重启客户端，对照官方目录 |
| 生成迟迟没结束 | 原任务 ID 与实际状态 | 查询原任务，不重复创建；失败后按错误补充输入 |
| 继续任务被拒绝 | 是否仍在运行；完成后是否给了新要求 | 按当前状态选择查询或继续 |
| 查不到原型 | 是否本人创建的 proto2，筛选条件是否过窄 | 核对账号和归属，放宽筛选后再查 |
| 导入失败 | 输入是否实际 HTML，而不是工程或外部 URL | 转换为支持的输入，先用一页定位问题 |
| 导出链接打不开 | 对应账号登录状态与链接有效期 | 在正确账号浏览器打开，必要时重新取得链接 |
生成结果怎样进入下一轮工作
第一次操作可以只做三页预约流程：连接正确账号、得到一个任务、检查预览、导入原型。下一次规则变更则继续原任务，已有设计交接则读取画布；把任务 ID、原型项目与本轮修改要求对应保存，就不用反复猜哪份是当前版本。
HTML 原型重点检查用户能否完成预约、取消和失败恢复；PRD 重点核对规则是否来自已确认材料；React/Vue 产物还要检查依赖、数据接口、权限与测试。需要连续整理访谈、PRD 和本地文件时，可使用墨刀 AI 客户端的本地项目工作流组织输入，再把需要设计和评审的结果接回墨刀。
