https://api.mcphero.app/mcp/<server-id>/mcp

技能名称: create-mcp-server
详细描述:

使用 MCPHero 创建 MCP 服务器

MCPHero 让智能体能够构建自己的工具。智能体无需在每次运行时消耗令牌处理 API 架构、SQL 查询和输出解析，而是只需创建一次持久化的 MCP 服务器，之后便可永久调用。一个原本需要 50,000 令牌的集成任务，现在仅需 50 令牌的工具调用。

本技能涵盖使用 mcpheroctl CLI 工作流端到端构建服务器的完整流程。

生产环境 API 基础 URL: https://api.mcphero.app/api

---

前置条件

使用本技能前，用户必须已安装并认证 mcpheroctl。

安装 mcpheroctl

bash

通过 Homebrew (macOS/Linux)

brew install arterialist/mcpheroctl/mcpheroctl

通过 uv (跨平台)

uv tool install mcpheroctl

认证

1. 1. 登录 MCPHero 控制台。
2. 进入 设置 → 组织 → 开发者。
3. 点击 创建 API 密钥 并复制令牌。
4. 运行：

bash
mcpheroctl auth login --token <你的组织令牌>

验证

bash
mcpheroctl auth status

---

向导流水线

CLI 遵循以下线性流程。在任何异步步骤之后，轮询 wizard state 并检查 processing_status == idle，然后再继续。

1. 1. create-session → 返回 serverid（保存它，后续所有步骤都需要）
2. conversation (循环) → 收集需求；当 isready: true 时停止
3. start → 进入工具建议阶段（异步 → 轮询）
4. list-tools → 审查 AI 建议的工具
5. refine-tools (可选) → 迭代调整工具直到满意（异步 → 轮询）
6. submit-tools → 确认选择（删除未选中的工具）
7. (自动环境变量建议) → 在 submit-tools 后自动触发（异步 → 轮询）
8. list-env-vars → 审查建议的环境变量
9. refine-env-vars (可选) → 迭代调整环境变量（异步 → 轮询）
10. submit-env-vars → 提供实际值（即使列表为空也要调用——后端需要此步骤来转换状态）
11. set-auth → 为服务器生成 bearer 令牌
12. generate-code → 触发代码生成（异步 → 轮询）
13. deploy → 部署到 MCPHero 运行时 → 返回 serverurl + bearertoken

始终调用 submit-env-vars，即使 list-env-vars 返回 []。后端需要此步骤来转换到下一个状态。如果没有环境变量，只需在不带 --var 标志的情况下调用它。

---

状态机

wizard state 中的 setup_status 字段指示当前所处阶段：

gathering_requirements → 用户正在讨论需求
tools_generating → LLM 正在生成工具建议（异步，轮询）
tools_selection → 工具已准备好供审查/选择
envvarsgenerating → LLM 正在生成环境变量建议（异步，轮询）
envvarssetup → 环境变量已准备好供审查/提交
auth_selection → 已准备好设置认证
code_generating → LLM 正在生成代码（异步，轮询）
code_gen → 代码已准备好供审查
deployment_selection → 已准备好部署
ready → 服务器已部署并运行

以 generating 结尾的状态是瞬态的——轮询直到它们转换。processingstatus 字段是可靠的检查方式：idle 表示完成，processing 表示等待，error 表示检查 processing_error。

---

完整向导示例

始终使用 --json 以获得可脚本化的输出。没有它，人类友好的消息会发送到 stderr，可能干扰解析。

bash

1. 创建会话

mcpheroctl wizard create-session --json

→ {server_id: abc-123-...}

SERVER_ID=abc-123-...

2. 描述需求（迭代直到 is_ready: true）

mcpheroctl wizard conversation $SERVER_ID --json \ -m 我有一个 PostgreSQL 数据库，包含 customers 和 orders 表。我需要工具来按名称查找客户、获取客户的订单以及获取过去一小时的订单。

重复发送后续消息，直到输出显示：is_ready: true

3. 开始工具建议（异步）

mcpheroctl wizard start $SERVER_ID --json

→ {status: processing}

轮询直到处理完成（检查 processingstatus，而非 setupstatus）

until mcpheroctl wizard state $SERVER_ID --json 2>/dev/null | \ python3 -c import sys,json; exit(0 if json.load(sys.stdin).get(processing_status)==idle else 1); do sleep 3 done

4. 审查工具（状态应为 tools_selection）

mcpheroctl wizard list-tools $SERVER_ID --json

5. 如有需要则优化（异步 → 再次轮询）

mcpheroctl wizard refine-tools $SERVER_ID --json \ -f 为找不到客户的情况添加错误处理。将 getcustomersorders 重命名为 getordersby_customer。

6. 提交选定的工具 ID

mcpheroctl wizard submit-tools $SERVER_ID --json \ --tool-id <工具-uuid-1> \ --tool-id <工具-uuid-2> \ --tool-id <工具-uuid-3>

7. 等待环境变量建议（自动触发，状态变为 envvarssetup）

until mcpheroctl wizard state $SERVER_ID --json 2>/dev/null | \ python3 -c import sys,json; exit(0 if json.load(sys.stdin).get(processing_status)==idle else 1); do sleep 3 done

8. 审查环境变量

mcpheroctl wizard list-env-vars $SERVER_ID --json

9. 提交环境变量值（格式：VAR_UUID=VALUE）

即使 list-env-vars 返回 [] 也始终调用此命令——后端需要它来转换状态。

有环境变量时：

mcpheroctl wizard submit-env-vars $SERVER_ID --json \ --var <环境变量-uuid-1>=localhost \ --var <环境变量-uuid-2>=5432

无环境变量时（空列表）：

mcpheroctl wizard submit-env-vars $SERVER_ID --json

10. 设置认证

mcpheroctl wizard set-auth $SERVER_ID --json

→ {bearer_token: ...} ← 保存此令牌

11. 生成代码（异步 → 轮询）

mcpheroctl wizard generate-code $SERVER_ID --json until mcpheroctl wizard state $SERVER_ID --json 2>/dev/null | \ python3 -c import sys,json; exit(0 if json.load(sys.stdin).get(processing_status)==idle else 1); do sleep 3 done

12. 部署

mcpheroctl wizard deploy $SERVER_ID --json

→ {serverurl: /mcp/<服务器-id>/mcp, bearertoken: ..., step: complete}

重要提示：deploy 返回的是相对路径的 server_url，例如 /mcp//mcp。需要拼接基础域名才能获得完整 URL：

https://api.mcphero.app/mcp/<服务器-id>/mcp

---

服务器管理

bash
mcpheroctl server list --json [客户ID] # 列出所有服务器
mcpheroctl server get 服务器ID --json # 获取服务器详情 + 状态
mcpheroctl server update 服务器ID # 更新名称/描述
mcpheroctl server delete 服务器ID --yes # 删除（不可逆）
mcpheroctl server api-key 服务器ID --json # 获取 bearer 令牌

---

轮询模式

可靠的轮询方式是检查 processingstatus，而非 setupstatus：

bash
until mcpheroctl wizard state $SERVER_ID --json 2>/dev/null | \
python3 -c import sys,json; exit(0 if json.load(sys.stdin).get(processing_status)==idle else 1); do
sleep 3
done

---

将已部署的服务器连接到 MCP 客户端

在 deploy