四步连接您的 Agent。
对于 Claude、ChatGPT 或 Codex,建议使用 OAuth 连接,因为它可以安全地开放当前登录用户获准使用的 HumanDesign.ai 工具。
1. 添加托管端点
端点
https://mcp.humandesign.ai/选择 Remote HTTP 或 Streamable HTTP。请勿再次添加 /mcp :标准端点位于域名根路径。
2. 完成身份验证
使用客户端的 MCP Authenticate 或 Connect 操作,并完成 HumanDesign.ai 浏览器登录。Claude Code 用户可以运行 claude mcp login human-design-ai;Codex 用户可以运行 codex mcp login human_design_ai.
如果只需要六项计算/参考工具,仍可通过 Bearer 或 X-Api-Key 方式使用 API 密钥。
3. 发现可用工具
JSON-RPC
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}发现工具是免费的。OAuth 工具可见性取决于服务器派发的能力授权、Free/Individual/Personal/Pro 会员资格、工作区角色、所有权和产品权限。API 密钥可见性取决于单独的 Free/Creator/Startup/Business API 计划。
4. 从您的主图开始
请 Agent 调用 chart_get_primary。如果尚无主图,Free、Individual、Personal 和 Pro 用户可以使用 chart_generate:先检查标准化后的出生信息和一单位预览,再确认执行。系统按账户所有权查找已保存的图表,不会通过搜索“Kyle”或“我的图表”等名称来确定。读取他人已授权图表需要 Personal 或 Pro。
Connection, initialize, ping, tools/list、读取库内容、检查状态和渲染已有图表均不消耗积分。新计算的主图恰好消耗一个计算单位;渲染不会再次收费。
计算可信度如何保障
Agent 本身不会计算图表。HumanDesign.ai 会在消耗配额前验证日期、地点、IANA 时区和夏令时上下文,然后返回计算服务生成的版本化结果。地点含糊或输入无效时会返回清晰的错误,不会消耗单位。如果出生时间未知,服务会记录使用当地正午,并提示对时间敏感的图表详情可能不同。
安全地重试计算
会消耗配额的 MCP 工具 generate_chart, generate_composite_chart和 get_transits 需要提供 idempotencyKey。对于一次有意的重试,请使用相同的密钥和标准化参数;新任务则使用新密钥。匹配的重试不会额外消耗配额,但可能会确定性地重新计算结果,并非逐字节重放已存储的响应。MCP 行运调用需要明确指定日期,确保重试对应同一时刻。REST 和 Agent HTTP 客户端可以在支持的有界非流式操作中发送 Idempotency-Key ;在兼容性推出期间此项仍为可选,因此不提供该字段的调用无法消除传输重试造成的重复。Batch 和 SSE 不接受调用方提供的重试密钥,也不属于本重试去重约定的范围。
原始协议测试
使用 API 密钥的开发者可以直接初始化并调用计算工具:
初始化
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {
"name": "my-agent",
"version": "1.0.0"
}
}
}计算调用
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "generate_chart",
"arguments": {
"birthDateTime": "1990-05-15T14:30:00",
"timezone": "America/New_York",
"detailLevel": "core",
"idempotencyKey": "chart-1990-05-15-v1"
}
}
}