MCP server
The Model Context Protocol (MCP) is an open standard that lets AI assistants (Claude, GPT, custom agents) discover and call external tools. Instead of crafting HTTP requests, the AI client negotiates capabilities with the server and invokes tools by name.
THD exposes a single MCP endpoint that gives 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, the SAGE knowledge base, and read-only reference resources.
Endpoint
Transport: Streamable HTTP. Your MCP client handles the protocol automatically.
Authentication
Use the same API key you use for the REST API:
Generate or manage keys from your dashboard.
Access and metering
Access is enforced per tool based on the surface it touches, not by a single MCP 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 lacks access to a surface, the tool returns an error (e.g., "Your plan does not include the SAGE API. Upgrade…"). The other tools continue to work. 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 uses JSON-RPC over Streamable HTTP instead of plain REST, but the underlying calculations are identical.
Most tools return raw calculation data. query_sage returns a natural-language answer (answer and domain) from the knowledge base, identical to 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.