Tutorial / 10 minutes

Your first tool call

By the end of this page you will have an MCP client connected to Lumin, a working authentication header, and the response from a real astronomical computation. We will stay in the unauthenticated endpoint for the first call so you can verify the wiring before adding auth.

Step 1 - Pick an endpoint

Lumin exposes two MCP endpoints. Both speak Streamable HTTP and accept the standard MCP request shape. Pick based on the auth mode you want.

Step 2 - List the tools

Send a standard MCP tools/list request to confirm the connection works.

curl -X POST https://mcp.lumin.guru/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

You should see the full tool list returned in a single response.

Step 3 - Run your first tool

Compute a full KP chart. Birth-data tools all take the same five fields: birth_datetime, latitude, longitude, utc_offset_minutes, and ayanamsa.

curl -X POST https://mcp.lumin.guru/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_full_chart",
      "arguments": {
        "birth_datetime": "1992-08-14T04:32:00",
        "latitude": 6.927,
        "longitude": 79.861,
        "utc_offset_minutes": 330,
        "ayanamsa": "kp"
      }
    }
  }'

The response contains the ascendant, planetary positions, dasha state, cusps, and a current ruling planets snapshot. From here, you can chain the seven-phase reading protocol or call any of the 49 other tools.

Step 4 - Add authentication

For higher daily limits, add an API key to the header. Get a key from your developer panel at app.lumin.guru/developer.

curl -X POST https://mcp.lumin.guru/mcp \
  -H "Authorization: Bearer mcp_yourkey..." \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", ... }'

Where to next

• API key vs OAuth covers when each makes sense.
• Tool reference lists every tool with schemas and examples.
• Recover from errors covers retry, rate limits, and graceful degradation.