接入文档

三种接入方式，按你的场景选一种。

1. MCP（在 AI 助手里用）

适合 Claude 等支持 MCP 的客户端。装一次，之后直接说需求。

# 1) 设置 Key（在控制台创建）
export MRAGENTS_API_KEY=mra_live_xxxxxxxx

# 2) 启动
npx -y @mragents/mcp

客户端配置：

{
  "mcpServers": {
    "mragents": {
      "command": "npx",
      "args": ["-y", "@mragents/mcp"],
      "env": { "MRAGENTS_API_KEY": "mra_live_xxxxxxxx" }
    }
  }
}

⚠️ 国内网络注意

npx 默认走淘宝镜像，新发布的包镜像同步有延迟（几分钟到几小时），这期间会报 404 Not Found。改用官方源即可：

npx --registry=https://registry.npmjs.org -y @mragents/mcp

也可以不装任何东西，用远程 MCP：地址 https://mcp.mragents.ai/mcp，请求头带 Authorization: Bearer mra_live_xxxxxxxx。企业内网或 npx 拉不动时，这是最省事的方式。

2. REST（在自己的系统里用）

# 查技能目录
curl https://api.mragents.ai/v1/skills   -H "Authorization: Bearer $MRAGENTS_API_KEY"

# 报价（正式运行前先算钱）
curl -X POST https://api.mragents.ai/v1/skills/price   -H "Authorization: Bearer $MRAGENTS_API_KEY"   -H "Content-Type: application/json"   -d '{"sku":"shipment_check","input":{"company":"示例公司"}}'

# 运行
curl -X POST https://api.mragents.ai/v1/skills/run   -H "Authorization: Bearer $MRAGENTS_API_KEY"   -H "Content-Type: application/json"   -H "Idempotency-Key: my-unique-key-001"   -d '{"sku":"shipment_check","input":{"company":"示例公司"}}'

# 取结果
curl https://api.mragents.ai/v1/tasks/tsk_xxxx   -H "Authorization: Bearer $MRAGENTS_API_KEY"

3. 几个要点

幂等：带 Idempotency-Key 头，同键同入参永远只跑一次、只扣一次费
受理即预扣：提交时冻结积分；取消或失败时未开始的阶段退回
异步技能：返回 task_id，用 GET /v1/tasks/{task_id} 轮询
错误码：fault 字段告诉你该改请求（client）还是重试（capability/upstream）
字段命名：全部 snake_case；中文/英文按 Accept-Language

完整 API 参考

见仓库 docs/api/README.md（鉴权、全部端点、24 个错误码、配额与限流）。