Skip to content
Lumindocs
UseBuildChangelog
Open Lumin

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. Every request needs credentials, so we start with an API key and stay on it throughout.

Step 1 - Pick an auth mode

There is one MCP endpoint, https://mcp.lumin.guru/mcp. It speaks Streamable HTTP, accepts the standard MCP request shape, and reads the Authorization header to decide which mode you are in.

ModeHeaderMetered against
API keyBearer mcp_...the key's monthly allowance
OAuth 2.1Bearer access tokenthe signed-in account's monthly allowance

The calls below use an API key. Generate one at app.lumin.guru/developer first. Signing in there is an email address plus a six digit code sent to it, no password.

Step 2 - List the tools

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

bash
curl -X POST https://mcp.lumin.guru/mcp \
  -H "Authorization: Bearer mcp_yourkey..." \
  -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.

bash
curl -X POST https://mcp.lumin.guru/mcp \
  -H "Authorization: Bearer mcp_yourkey..." \
  -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 157 other tools.

Step 4 - Switch to OAuth for per-user access

An API key runs on behalf of your application. When each end user needs their own account, limits, and usage attribution, keep the same URL and let the client run the OAuth flow instead. Your user signs in with an email address and a six digit code, then their token goes in the same header shape.

bash
curl -X POST https://mcp.lumin.guru/mcp \
  -H "Authorization: Bearer <user access token>" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", ... }'

Where to next

PreviousOverviewNextIntegrate into your app