Connect to HumanDesign.ai MCP

Before you start

HumanDesign.ai MCP gives compatible AI clients structured Human Design tools. This guide covers the calculation and reference catalog that uses an API key. If your client supports the HumanDesign.ai OAuth connection, use that flow when you need account-connected access such as saved platform data; OAuth permissions and availability are chosen during sign-in.

The canonical MCP endpoint is https://mcp.humandesign.ai/. Use POST / for MCP requests. GET / is not a connection test and returns 405 Method Not Allowed. POST /mcp is a compatibility alias.

Add your API key safely

Use one of these request headers. Do not put an API key in a URL, commit it to a repository, or paste it into a chat.

Authorization: Bearer YOUR_HDAI_API_KEY

or:

X-Api-Key: YOUR_HDAI_API_KEY

Connect and discover your tools

1. Configure your MCP client with https://mcp.humandesign.ai/.
2. Send initialize with protocol version 2025-11-25.
3. Send notifications/initialized.
4. Call tools/list and use only the tools returned for your key.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": { "name": "your-client", "version": "1.0.0" }
  }
}

Discovery calls such as initialize, ping, and tools/list do not consume calculation quota. A successful tools/call consumes one shared API unit; validation failures and unavailable tools do not.

Call a tool

Use the tool name and input schema returned by tools/list. For example, a core chart request has this shape:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "generate_chart",
    "arguments": {
      "birthDateTime": "1990-05-15T14:30:00",
      "timezone": "America/New_York",
      "detailLevel": "core"
    }
  }
}

Read the result

Successful calls return a short readable summary, a JSON text block, and structuredContent. The structured response uses a versioned envelope with version, tool, data, meta, and an optional error field.

The current calculation/reference catalog exposes tools only. Do not expect MCP prompts, MCP resources, report-generation tools, server sessions, or chart image blocks from this catalog.