Connect your agent in four steps.

For Claude, ChatGPT, or Codex, OAuth is the recommended connection because it can safely expose the signed-in user's permitted HumanDesign.ai tools.

1. Add the hosted endpoint

https://mcp.humandesign.ai/

Choose remote HTTP or Streamable HTTP. Do not add /mcp again: the canonical endpoint is the domain root.

2. Authenticate

Use the client's MCP Authenticate or Connect action and complete the HumanDesign.ai browser login. Claude Code users can run claude mcp login human-design-ai; Codex users can run codex mcp login human_design_ai.

If you only need the six calculation/reference tools, an API key remains available through Bearer or X-Api-Key authentication.

3. Discover your tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Discovery is free. OAuth tool visibility follows the user's server-derived capability grants, Free/Individual/Personal/Pro membership, workspace role, ownership, and product entitlements. API-key visibility follows the separate Free/Creator/Startup/Business API plan.

4. Start with your primary chart

Ask the agent to call chart_get_primary. If no primary chart exists, Free, Individual, Personal, and Pro members can use chart_generate: first review its normalized birth details and one-unit preview, then confirm execution. The saved chart is resolved by account ownership, never by searching for a name such as “Kyle” or “My Chart.” Reading other people's authorized charts requires Personal or Pro.

How calculation trust works

The agent does not calculate a chart itself. HumanDesign.ai validates the date, location, IANA timezone, and daylight-saving context before quota is consumed, then returns the versioned result from its calculation service. Ambiguous locations and invalid inputs return a clear error without spending a unit. If the birth time is unknown, the service records that it used local noon and warns that time-sensitive chart details may differ.

Safe calculation retries

The consuming MCP tools generate_chart, generate_composite_chart, and get_transits require an idempotencyKey. Reuse the same key with identical normalized arguments for one intended retry, and use a new key for new work. A matching retry consumes no additional quota and may deterministically recompute the result; it is not byte-for-byte replay of a stored response. MCP transit calls require an explicit date so a retry always refers to the same moment. Direct REST and Agent HTTP clients can send Idempotency-Key on supported bounded non-streaming operations; it remains optional during the compatibility rollout, so calls without it cannot deduplicate a transport retry. Batch and SSE reject caller retry keys and are outside this retry-deduplication contract.

Raw protocol testing

Developers using an API key can initialize and call a calculation tool directly:

{
  "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"
    }
  }
}

Choose your client

Claude · Codex · Cursor · VS Code · Plugin downloads