MCP Tools Reference

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

Authentication

All requests require Authorization: Bearer thd_YOUR_API_KEY in the HTTP headers. The JSON-RPC body does not carry auth — it goes in the transport layer.

generate_chart

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

Input schema

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

Example request

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

Example response

{
"jsonrpc": "2.0",
"id": 1,
"result": {
  "content": [
    {
      "type": "text",
      "text": "{\"type\":\"Generator\",\"strategy\":\"To Respond\",\"authority\":\"Sacral\",\"profile\":\"3/5\",\"definition\":\"Single\",\"incarnationCross\":\"Right Angle Cross of Laws\",\"variable\":\"PLL DRR\",\"centers\":{\"defined\":[\"sacral\",\"throat\",\"g\"],\"open\":[\"head\",\"ajna\",\"heart\",\"spleen\",\"solar_plexus\",\"root\"]},\"channels\":[{\"gates\":\"1-8\",\"name\":\"Inspiration\",\"circuitry\":\"Individual\"}],\"personality\":{\"Sun\":{\"gate\":38,\"line\":3}},\"design\":{\"Sun\":{\"gate\":28,\"line\":5}}}"
    }
  ]
}
}

generate_composite

Generate a composite chart analyzing the connection between two people.

Input schema

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

Example request

tools/calljson

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

Example response

{
"jsonrpc": "2.0",
"id": 2,
"result": {
  "content": [
    {
      "type": "text",
      "text": "{\"compositeType\":\"Generator-Projector\",\"connectionChannels\":[{\"gates\":\"34-20\",\"name\":\"Charisma\",\"type\":\"electromagnetic\"}],\"dominantDefinition\":\"Split\",\"sharedCenters\":{\"defined\":[\"sacral\",\"throat\"],\"compromise\":[\"g\"]},\"person1\":{\"type\":\"Generator\"},\"person2\":{\"type\":\"Projector\"}}"
    }
  ]
}
}

get_transits

Get planetary transit data for a date range. Returns gate/line positions for all planets at the specified granularity.

Input schema

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

Example request

tools/calljson

{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
  "name": "get_transits",
  "arguments": {
    "startDate": "2026-03-20",
    "endDate": "2026-03-21",
    "granularity": "daily"
  }
}
}

Example response

{
"jsonrpc": "2.0",
"id": 3,
"result": {
  "content": [
    {
      "type": "text",
      "text": "{\"transits\":[{\"date\":\"2026-03-20\",\"planets\":{\"Sun\":{\"gate\":25,\"line\":2},\"Earth\":{\"gate\":46,\"line\":2},\"Moon\":{\"gate\":51,\"line\":4},\"Mercury\":{\"gate\":17,\"line\":6},\"Venus\":{\"gate\":21,\"line\":3},\"Mars\":{\"gate\":4,\"line\":1},\"Jupiter\":{\"gate\":45,\"line\":5},\"Saturn\":{\"gate\":47,\"line\":2}}}]}"
    }
  ]
}
}

get_planetary_return

Calculate when a planet returns to its natal position, generating a return chart for a specific year.

Input schema

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

Example request

tools/calljson

{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
  "name": "get_planetary_return",
  "arguments": {
    "birthDate": "1990-05-15",
    "birthTime": "14:30",
    "birthLocation": "New York, NY",
    "planet": "saturn",
    "year": 2026
  }
}
}

Example response

{
"jsonrpc": "2.0",
"id": 4,
"result": {
  "content": [
    {
      "type": "text",
      "text": "{\"planet\":\"Saturn\",\"returnDate\":\"2026-07-12T03:45:00Z\",\"natalPosition\":{\"gate\":47,\"line\":2,\"longitude\":234.56},\"returnChart\":{\"type\":\"Generator\",\"strategy\":\"To Respond\",\"authority\":\"Sacral\",\"profile\":\"3/5\"}}"
    }
  ]
}
}