Skip to content
docs
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 account's monthly allowance, shared across its keys
OAuth 2.1Bearer access tokenthe signed-in account's monthly allowance

The calls below use an API key. Generate one at developer.lumin.guru 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 "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Note

The transport requires Accept to contain both application/json and text/event-stream on every POST, or it answers 406. A successful call does not come back as a JSON body either: the response is an SSE stream, one data: line carrying the JSON-RPC payload. To read it with curl and jq, add --no-buffer and strip the data: prefix first: curl ... --no-buffer | sed -n 's/^data: //p' | jq '.result'.

You should see all 221 tools returned in a single response: 218 engine-backed tools plus the 3 meta-tools that carry the reading protocol.

Step 3 - Call set_birth_profile first

Every reading starts here. Pass the birth data and the user's question, and the response comes back with the numbered list of tools to call for that question plus the minimum number of calls required before an answer is allowed.

bash
curl -X POST https://mcp.lumin.guru/mcp \
  -H "Authorization: Bearer mcp_yourkey..." \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "set_birth_profile",
      "arguments": {
        "birth_datetime": "1992-08-14T04:32:00",
        "latitude": 6.927,
        "longitude": 79.861,
        "utc_offset_minutes": 330,
        "ayanamsa": "kp",
        "question": "When will I get married?"
      }
    }
  }'

The result confirms the profile and then prints a reading plan: classified as FULL READING (Marriage and relationships), minimum tool calls before you answer: 20, followed by the tools in order. Those floors are mandatory. Read reading depth and call floors before you size your agent loop: a loop capped at eight tool calls cannot produce a valid reading.

The server is stateless

set_birth_profile stores nothing. Repeat the same birth fields in every call that follows. If your instructions arrived truncated, which some clients do, get_reading_protocol returns the whole methodology as a tool result instead.

Step 4 - Run your first computation

Compute a full KP chart, the first entry in every reading plan. 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 "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "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. Keep working down the plan from step 3, or call any of the 217 other engine-backed tools.

Step 5 - 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 "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", ... }'

Where to next

PreviousOverviewNextClaude Code plugin