MCP Server
The Model Context Protocol (MCP) is an open standard that lets AI assistants — Claude, GPT, custom agents — discover and call external tools in a structured way. Instead of crafting HTTP requests, the AI client negotiates capabilities with the server and invokes tools by name.
THD exposes a single MCP endpoint giving AI agents the full developer API surface: Human Design charts, Western astrology, BaZi / Four Pillars, composite analysis, transits (all-planet, Moon, and full-chart), transit periods, eclipses, retrogrades, planetary returns, batch charts, location validation, and the SAGE knowledge base — plus read-only reference resources.
Endpoint
POST https://api.totalhumandesign.com/mcpTransport: Streamable HTTP (the MCP standard HTTP transport). Your MCP client handles the protocol automatically.
Authentication
Use the same API key you use for the REST API:
Authorization: Bearer thd_YOUR_API_KEYGenerate or manage keys from your dashboard.
Access & metering
Access is enforced per tool, by the surface it touches — not by one MCP-wide subscription:
- Chart tools (everything except
query_sage) require a plan with Chart access and count toward your monthly Chart requests meter. query_sagerequires a plan with SAGE access and counts toward your monthly SAGE responses meter.
If your tier doesn't include a surface, that tool returns a clear error — e.g. "Your plan does not include the SAGE API. Upgrade…" — which your agent can relay to the user. The other tools keep working. Most chart tools cost 1 chart request; the transit-range tools (get_transits, get_moon_transits, get_transit_chart) bill by range × granularity in chart requests; multi_chart bills 1 chart request per successful chart; query_sage costs 1 SAGE response.
Available capabilities
Tools (14)
| Tool | Surface | Description |
|---|---|---|
generate_chart | Chart | Full V2 Human Design chart from birth data |
generate_composite | Chart | Composite (relationship) chart for two people |
get_astrology_chart | Chart | Western astrology natal chart |
get_bazi_chart | Chart | BaZi / Four Pillars (Saju) chart |
get_transits | Chart | All-planet transit positions over a date range |
get_moon_transits | Chart | Moon-only transit positions over a date range |
get_transit_chart | Chart | Full HD charts computed at each point in a range |
get_transit_periods | Chart | Gate entry/exit events over a date range |
get_eclipses | Chart | Solar & lunar eclipse moments |
get_retrogrades | Chart | Retrograde station dates |
get_planetary_return | Chart | Planetary return chart for a year |
multi_chart | Chart | Batch HD charts (up to 10) |
validate_location | Chart | Resolve a location to city / timezone / coordinates |
query_sage | SAGE | Natural-language answers from the THD knowledge base |
Resources (2)
| URI | Description |
|---|---|
thd://reference/terminology | Human Design terminology — types, strategies, authorities, centers, channels, gates |
thd://reference/chart-fields | V2 chart response field definitions, data types, and nested object structure |
MCP vs REST
| Use case | Choose |
|---|---|
| AI agent integration (Claude Desktop, Cursor, custom LLM pipelines) | MCP |
| Traditional app, mobile client, server-to-server | REST API |
Every MCP tool wraps the matching REST endpoint and returns the same data. The protocol layer differs — JSON-RPC over Streamable HTTP instead of plain REST — but the underlying calculations are identical.
Data + knowledge
Most tools return raw calculation data. query_sage is the exception — it returns an AI-synthesized natural-language answer (answer + domain) from the knowledge base, the same as the SAGE API over REST.
Next steps
- Quickstart — Connect your MCP client in 5 minutes
- Tools Reference — Input schemas and JSON-RPC examples for all 14 tools
- Resources Reference — Read-only reference data available to your agent