MCP Tools Reference

THD exposes 14 tools via MCP. Each is called with the JSON-RPC tools/call method over the Streamable HTTP transport at POST https://api.totalhumandesign.com/mcp.

Authentication & access

All requests require Authorization: Bearer thd_YOUR_API_KEY in the HTTP headers (the JSON-RPC body carries no auth). Each tool is gated by the surface it touches: chart tools need a plan with Chart access; query_sage needs SAGE access. A tool you're not entitled to returns { isError: true } with a message like "Your plan does not include the Chart API".

Every tool returns its result as JSON inside result.content[0].text. The tools/call envelope is identical for every tool — only name and arguments change:

tools/call envelopejson

{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": { "name": "<tool>", "arguments": { /* per-tool */ } }
}

Overview

Tool	Surface	Meter cost	Notes
`generate_chart`	Chart	1 chart request	Full V2 HD chart
`generate_composite`	Chart	1 chart request	Two-person relationship chart
`get_astrology_chart`	Chart	1 chart request	Western natal chart
`get_bazi_chart`	Chart	1 chart request	Four Pillars — needs `gender`
`get_transits`	Chart	range×granularity	All 13 planets
`get_moon_transits`	Chart	range×granularity	Moon only
`get_transit_chart`	Chart	range×granularity	Full HD chart per point
`get_transit_periods`	Chart	1 chart request	Gate entry/exit events (≤366 days)
`get_eclipses`	Chart	1 chart request	Solar/lunar eclipses (≤10 years)
`get_retrogrades`	Chart	1 chart request	Station dates (≤730 days)
`get_planetary_return`	Chart	1 chart request	Return chart for a year
`multi_chart`	Chart	1 chart request per success	Batch, up to 10
`validate_location`	Free	Not metered	Resolve a location
`query_sage`	SAGE	1 SAGE response	Knowledge-base answer

generate_chart

Generate a complete V2 Human Design chart. Returns type, strategy, authority, profile, centers, channels, gates, planetary positions, PHS, Variable, and more.

{
"birthDate": "string (YYYY-MM-DD)",
"birthTime": "string (HH:MM, 24h)",
"birthLocation": "string (city, state/country)"
}

tools/calljson

{
"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": {
  "name": "generate_chart",
  "arguments": { "birthDate": "1990-05-15", "birthTime": "14:30", "birthLocation": "New York, NY" }
}
}

Response (result.content[0].text is a JSON string):

{
"jsonrpc": "2.0", "id": 1,
"result": { "content": [ { "type": "text",
  "text": "{\"type\":\"Generator\",\"strategy\":\"To Respond\",\"authority\":\"Sacral\",\"profile\":\"3/5\",\"centers\":{...},\"channels\":[...],\"personality\":{...},\"design\":{...}}"
} ] }
}

generate_composite

Composite (relationship) chart for two people. Parameters are flat — person A uses birthDate/birthTime/birthLocation, person B uses the …1 suffix.

{
"birthDate": "string (Person A, YYYY-MM-DD)",
"birthTime": "string (Person A, HH:MM)",
"birthLocation": "string (Person A)",
"birthDate1": "string (Person B, YYYY-MM-DD)",
"birthTime1": "string (Person B, HH:MM)",
"birthLocation1": "string (Person B)"
}

tools/calljson

{
"jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": {
  "name": "generate_composite",
  "arguments": {
    "birthDate": "1990-05-15", "birthTime": "14:30", "birthLocation": "New York, NY",
    "birthDate1": "1988-11-22", "birthTime1": "09:15", "birthLocation1": "Los Angeles, CA"
  }
}
}

get_astrology_chart

Western astrology natal chart (planets, signs, houses, aspects).

{
"birthDate": "string (YYYY-MM-DD)",
"birthTime": "string (HH:MM)",
"birthLocation": "string"
}

get_bazi_chart

BaZi / Four Pillars (Saju) chart. gender is required (sets luck-pillar direction).

{
"birthDate": "string (YYYY-MM-DD)",
"birthTime": "string (HH:MM)",
"birthLocation": "string",
"gender": "string (\"male\" | \"female\")"
}

get_transits

All 13 Human Design planets' transit positions over a date range. Bills by range × granularity.

{
"startDate": "string (YYYY-MM-DD)",
"endDate": "string (YYYY-MM-DD)",
"granularity": "string (\"daily\" | \"hourly\")"
}

get_moon_transits

Moon-only transit positions (gate, line, sign, phase). The Moon moves through all 64 gates in ~28 days. Bills by range × granularity.

{
"startDate": "string (YYYY-MM-DD)",
"endDate": "string (YYYY-MM-DD)",
"granularity": "string (\"daily\" | \"hourly\")"
}

get_transit_chart

Full Human Design charts (Type, Authority, Channels, Centers, Variables) computed at each point in a range — no birth location needed. Bills by range × granularity.

{
"startDate": "string (YYYY-MM-DD)",
"endDate": "string (YYYY-MM-DD)",
"granularity": "string (\"daily\" | \"hourly\", default hourly)"
}

get_transit_periods

Gate entry/exit events — when each HD planet changes gate over a range (≤ 366 days). Returns events, not raw positions.

{
"startDate": "string (YYYY-MM-DD)",
"endDate": "string (YYYY-MM-DD)"
}

get_eclipses

Exact solar and lunar eclipse moments (UTC datetime, type, visibility) over a range (≤ 10 years).

{
"startDate": "string (YYYY-MM-DD)",
"endDate": "string (YYYY-MM-DD)",
"solarOnly": "boolean (optional)",
"lunarOnly": "boolean (optional)"
}

get_retrogrades

Retrograde station dates with HD gate positions and duration (≤ 730 days).

{
"startDate": "string (YYYY-MM-DD)",
"endDate": "string (YYYY-MM-DD)",
"planets": "string (optional, comma-separated, e.g. \"mercury,venus\")"
}

get_planetary_return

When a planet returns to its natal position, with the return chart for a year.

{
"birthDate": "string (YYYY-MM-DD)",
"birthTime": "string (HH:MM)",
"birthLocation": "string",
"planet": "string (e.g. \"saturn\", \"jupiter\", \"chiron\")",
"year": "number"
}

multi_chart

Batch HD charts for up to 10 people in one call. Returns one result per entry; bills 1 chart request per successful chart.

{
"charts": [
  { "birthDate": "1990-05-15", "birthTime": "14:30", "birthLocation": "New York, NY" },
  { "birthDate": "1988-11-22", "birthTime": "09:15", "birthLocation": "Los Angeles, CA" }
]
}

validate_location

Resolve a birth location to a city, timezone, and coordinates before generating a chart. Returns { valid: true, resolved: {...} } or { valid: false, error }.

{
"birthLocation": "string (e.g. \"New York, NY\")",
"birthDate": "string (optional, YYYY-MM-DD, for timezone)",
"birthTime": "string (optional, HH:MM)"
}

query_sage

Ask the THD knowledge base (Human Design, Western astrology, BaZi) a natural-language question. Requires SAGE access. Returns { answer, domain }.

{
"query": "string (your question, 2-500 characters)"
}

tools/calljson

{
"jsonrpc": "2.0", "id": 14, "method": "tools/call",
"params": { "name": "query_sage", "arguments": { "query": "What is a Projector's strategy?" } }
}