MCP quickstart

Configure an MCP client to call THD API tools.

1. Get an API key

Create an account and generate an API key from the dashboard. Keys use the thd_abc123... format.

Your plan determines tool access. A plan with Chart access unlocks chart tools. SAGE access unlocks query_sage. Calling a restricted tool returns a "your plan does not include the … API" error. Other tools continue to function. See billing.

2. Configure your MCP client

Claude Desktop

claude_desktop_config.jsonjson
{
"mcpServers": {
  "thd": {
    "url": "https://api.totalhumandesign.com/mcp",
    "headers": {
      "Authorization": "Bearer thd_YOUR_KEY"
    }
  }
}
}

Add this to the Claude Desktop configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Cursor

.cursor/mcp.jsonjson
{
"mcpServers": {
  "thd": {
    "url": "https://api.totalhumandesign.com/mcp",
    "headers": {
      "Authorization": "Bearer thd_YOUR_KEY"
    }
  }
}
}

Place this in .cursor/mcp.json at the project root or in the global Cursor config.

TypeScript SDK

connect.tstypescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
new URL("https://api.totalhumandesign.com/mcp"),
{
  requestInit: {
    headers: {
      Authorization: "Bearer thd_YOUR_KEY",
    },
  },
}
);

const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

// List available tools
const { tools } = await client.listTools();
console.log(tools.map(t => t.name));

// Call a tool
const result = await client.callTool({
name: "generate_chart",
arguments: {
  birthDate: "1990-05-15",
  birthTime: "14:30",
  birthLocation: "New York, NY",
},
});
console.log(result);

3. Test with generate_chart

In Claude Desktop or Cursor, test the connection by asking:

"Generate a Human Design chart for someone born May 15, 1990 at 2:30 PM in New York"

The agent calls generate_chart and returns the chart data.

If using the SDK, the code above includes a callTool example. The response contains chart data as a JSON string inside result.content[0].text.

4. Practical workflow

Combine tools and resources. Ask the agent:

"Generate a Human Design chart for May 15, 1990 at 14:30 in New York, then explain the results using Human Design terminology"

Behind the scenes, the agent:

  1. Calls generate_chart for the raw chart data.
  2. Reads thd://reference/terminology for Human Design definitions.
  3. Generates an explanation using both.
Resources load once

MCP clients cache resources per session. The terminology and chart-fields references fetch once and are reused across tool calls.

Next steps