墨刀AI MCP的使用方法可以概括为四步：在墨刀AI个人空间获取授权，使用远程HTTP地址连接支持MCP的客户端，根据目标选择HTML原型、React应用或PRD生成能力，再检查任务结果并将需要继续设计的页面导入墨刀。它适合已经在Codex、Claude Code、WorkBuddy、Qoder或TRAE中工作，希望不切换工具就获得可预览产物的产品、设计和研发人员。
截至2026年9月，墨刀官网推荐的服务地址是https://modao.cc/agent-py/ai/mcp，传输方式为Streamable HTTP。支持OAuth的客户端可以按界面完成授权；需要手动配置时，可使用个人空间令牌和modao-token请求头。旧教程中的本地stdio或npm包不应再作为新用户的默认接入方式。
墨刀AI MCP适合解决什么问题
墨刀AI MCP不是另一个独立的原型编辑器，而是把墨刀AI的生成能力接入你正在使用的AI工具。连接完成后，用户可以在当前对话中描述产品类型、目标用户、核心页面和期望产物，由客户端调用墨刀AI生成HTML原型、React应用或PRD，再返回任务状态、预览入口和产物信息。
如果你还需要理解协议角色、客户端与服务端之间如何协作，先阅读MCP是什么及其工作原理会更合适；本文只处理当前版本的配置、调用、验收和排错。
| 你的任务 | 更适合的入口 | 主要产物 |
|---|---|---|
| 在AI对话中生成原型、应用或PRD | 墨刀AI MCP | 任务、预览与对应产物 |
| 从业务系统主动发起HTTP请求 | 墨刀AI API | 接口响应与工程集成结果 |
| 连续处理本地文件和周期任务 | 墨刀AI客户端 | 本地文档、文件修改与自动任务 |
接入前需要准备什么
开始前要准备墨刀账号、支持Streamable HTTP的MCP客户端，以及一种授权方式。支持OAuth的客户端会跳转到墨刀完成登录授权；使用个人令牌时，应在墨刀AI头像菜单的“令牌设置”中创建令牌。真实令牌只保存在可信设备的用户级配置或环境变量中，不要写进文章、聊天记录、截图、共享文档和代码仓库。
需要实际配置时，应以墨刀AI MCP官方接入页展示的实时地址和客户端说明为准。产品页负责维护易变化的配置，本文重点说明不会随某个客户端界面变化的通用流程。
如何完成墨刀AI MCP连接
不同客户端的菜单位置不同，但连接逻辑相同：新增一个远程MCP服务，填写服务地址，完成OAuth授权或配置请求头，刷新服务列表，再确认能看到墨刀工具。手动配置时，服务名可以写为modao，地址使用官方当前推荐地址，请求头名称严格写为modao-token。
{
"mcpServers": {
"modao": {
"url": "https://modao.cc/agent-py/ai/mcp",
"headers": {
"modao-token": "YOUR_MODAO_TOKEN"
}
}
}
}这里的YOUR_MODAO_TOKEN只是占位符。客户端支持环境变量时，应让配置读取本机变量，而不是把真实令牌直接写入可同步或可提交的文件。连接成功后，先调用账号状态能力检查连接和可用权益，再开始生成，能更快区分“配置错误”和“权益不足”。
HTML原型、React应用和PRD怎么选
选择依据不是哪个产物看起来更高级，而是本轮要验证什么。需要尽快确认页面结构、布局和主要路径时，选择generate_html；需要更接近实现效果的交互Demo或工程起点时，选择generate_react；需求仍在梳理目标、规则和验收条件时，先使用generate_prd。目标还不明确时，可以调用通用的generate让服务选择产物，但仍要在指令中写清交付目的。
| 能力 | 适用阶段 | 人工检查重点 |
|---|---|---|
generate_html | 结构和流程验证 | 页面范围、路径、状态、内容层级 |
generate_react | 高保真Demo和开发衔接 | 组件状态、响应式、依赖、接口与工程规范 |
generate_prd | 需求梳理与评审准备 | 事实来源、业务规则、异常、验收标准 |
generate | 产物类型尚未确定 | 服务选择是否符合当前任务 |
从一句需求跑通完整任务
下面以“用户访谈预约”功能为例。不要只输入“做一个预约页面”，而应写清用户、页面、规则、输出和限制：
使用墨刀AI生成一个移动端用户访谈预约原型。
目标用户：收到研究邀请的注册用户。
页面范围：场次选择、信息填写、预约确认。
必须覆盖：场次已满、手机号校验失败、重复预约、提交失败和成功结果。
输出：可预览的HTML原型，并返回任务入口。
不要添加支付、社区或与预约无关的功能。- 先检查账号：确认MCP已经连接，并且账号状态与权益可用。
- 发起生成：明确要求HTML原型，避免服务在PRD、React应用和原型之间猜测。
- 查询任务：生成通常以任务形式执行，使用
get_task_result查看状态和结果，不要因短时间没有返回而重复创建相同任务。 - 检查预览：逐页验证场次选择、信息填写、确认和异常恢复路径。
- 继续编辑：结构确认后，使用
import_to_proto将适合继续设计的结果导入墨刀，并核对个人空间中的项目。
如果任务来自大量本地访谈记录、模板或多版本文件，使用墨刀AI客户端的本地项目工作流整理输入会更顺畅；MCP更适合在当前AI工具中发起明确的生成任务并回收结果。
生成结果应该怎样检查
MCP连接成功只说明调用链路可用，不代表产物已经可以交付。HTML原型要检查页面、跳转、权限和异常状态；React应用还要由研发检查依赖、组件边界、接口、可访问性、响应式和构建方式；PRD则要区分事实、假设和待确认规则，并补齐验收标准。
- 任务一致性：输出是否覆盖目标用户、页面范围和成功条件。
- 业务完整性：字段、规则、权限、异常和恢复动作是否存在。
- 事实可靠性：名称、数字、政策和业务约束是否来自可信资料。
- 工程可用性：生成代码是否符合团队技术栈、依赖和安全规范。
- 版本可追溯：任务入口、预览、导入结果和人工修改是否能够对应。
准备进入团队评审时，可以按照AI原型五轮迭代方法依次收敛任务、结构、状态、视觉和验收标准，而不是只讨论视觉效果。
常见连接问题怎么排查
连接后看不到工具时，按“地址、传输、认证、刷新、日志”的顺序检查。首先确认地址完整且没有多余字符；其次确认客户端使用HTTP或Streamable HTTP，而不是照搬旧教程中的stdio配置；再核对请求头名称是否严格为modao-token、令牌是否有效。保存后刷新MCP列表或重启客户端，并查看连接日志中的状态码和错误信息。
| 现象 | 优先检查 | 处理方式 |
|---|---|---|
| 服务无法连接 | 地址与传输类型 | 改用官方当前Streamable HTTP地址 |
| 提示未授权 | OAuth状态或Token/Header | 重新授权，或更新本机保存的有效令牌 |
| 连接成功但没有工具 | 客户端刷新与服务列表 | 刷新MCP、重启客户端并查看日志 |
| 生成任务长时间未结束 | 任务状态 | 查询原任务，不要连续重复创建 |
| 调用被权益限制 | 账号状态 | 先确认当前账号权益与实时规则 |
如果团队需要从自己的业务系统直接控制请求参数、响应处理和后续自动化，应比较墨刀AI API的REST接口方式，不要把MCP客户端配置当成后端接口集成方案。
令牌、权益和团队使用边界
个人空间令牌等同于账号访问凭证。优先保存在用户级、本机配置或环境变量中，不提交Git、不放入共享模板、不贴进对话，也不出现在截图里。怀疑泄露时，应立即在令牌设置中删除旧令牌并重新创建。
MCP调用会复用墨刀线上生成链路，任务消耗遵循当前墨刀账号的实时权益规则。团队使用时还要约定谁可以创建令牌、哪些项目允许调用、生成结果由谁验收，以及离职或设备丢失时如何撤销凭证。对于客户数据、商业秘密或受监管信息，应先遵守组织的数据处理制度，不要因为工具连接成功就扩大输入范围。
墨刀AI MCP常见问题
必须安装本地npm包吗？
当前新用户不需要把旧版npm或stdio方案作为默认方式。官方当前推荐使用远程Streamable HTTP地址，具体配置以接入页的实时说明为准。
OAuth和个人令牌应该选哪个？
客户端提供官方OAuth流程时，可以按界面完成授权；需要通用手动配置或自定义请求头时，使用个人空间令牌。无论哪种方式，都只授予完成当前任务所需的账号范围，并保管好凭证。
生成的React代码可以直接上线吗？
不应直接视为生产版本。生成结果适合作为交互Demo或工程起点，正式上线前仍需研发检查依赖、数据接口、权限、安全、性能、可访问性和测试覆盖。
生成结果保存在哪里？
官方当前说明中，调用归属于授权账号的墨刀个人空间；任务完成后会返回任务信息、预览入口和对应产物。导入原型后，还应在个人空间核对项目名称、版本和可编辑内容。
第一次使用墨刀AI MCP时，先选择一个范围明确、容易验收的真实任务：完成连接，指定一种产物，查询同一个任务并检查结果，再决定是否导入墨刀。跑通这条最小链路后，再分别扩展到React应用、PRD和团队工作流，问题会更容易定位。
