Skip to content
docs
UseBuildChangelog
Open Lumin

Guide

Test locally

Lumin is a hosted service, so there is nothing to install. Local testing means iterating your client on a laptop while it calls the public Lumin endpoint.

The endpoint to point at

Everything runs against https://mcp.lumin.guru/mcp. For routine development, send an API key. Switch to OAuth on the same URL when you want per-user attribution. Either way, credentials go on every call.

  • API key: Authorization: Bearer mcp_..., metered against the key's monthly allowance.
  • OAuth 2.1: Authorization: Bearer plus the user's access token, metered against their account's monthly allowance.

Use MCP Inspector for interactive debugging

The official @modelcontextprotocol/inspector CLI gives you a UI to call any tool with structured inputs and inspect the full response. Best way to learn the tool surface.

bash
npx @modelcontextprotocol/inspector https://mcp.lumin.guru/mcp

Set the Authorization header to your API key in the Inspector before you call anything.

curl recipes for scripted runs

List tools to confirm the connection works. Expect 221: 218 engine-backed tools plus the 3 meta-tools.

Note

The transport requires Accept to contain both application/json and text/event-stream on every POST, or it answers 406. A successful response is not a JSON body either, it is an SSE stream, so a plain | jq pipe fails: strip the data: prefix first with sed -n 's/^data: //p', as in the recipes below.

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"}' \
  --no-buffer | sed -n 's/^data: //p' | jq '.result.tools | length'

Call a single tool with realistic birth data:

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": "get_full_chart",
      "arguments": {
        "birth_datetime": "1992-08-14T04:32:00",
        "latitude": 6.927,
        "longitude": 79.861,
        "utc_offset_minutes": 330,
        "ayanamsa": "kp"
      }
    }
  }' --no-buffer | sed -n 's/^data: //p' | jq '.result'

Pin canonical test profiles

Hard-code two or three birth profiles in your test fixtures and reuse them across runs. The KP results are deterministic, so the same input always returns the same output. That makes regressions in your client easy to spot.

typescript
// fixtures/profiles.ts
export const PROFILE_A = {
  birth_datetime: "1992-08-14T04:32:00",
  latitude: 6.927,
  longitude: 79.861,
  utc_offset_minutes: 330,
  ayanamsa: "kp" as const,
};

export const PROFILE_B = {
  birth_datetime: "1985-01-23T09:15:00",
  latitude: 28.6139,
  longitude: 77.2090,
  utc_offset_minutes: 330,
  ayanamsa: "kp" as const,
};

Watch out for time-dependent tools

A small group of tools take the current moment as input and therefore produce different output on every call. Do not use these in snapshot tests:

For these, either pass an explicit query_datetime / scan_start argument so the result is reproducible, or accept that the response varies and assert only on shape.

Check the reading plan without spending a reading

get_reading_protocol takes no birth data, so one call shows you the tool list and the floor a given question will trigger. It is the cheapest way to see what your integration is about to spend before you run the whole chain.

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_reading_protocol",
      "arguments": { "question": "What is my nakshatra?" }
    }
  }' --no-buffer | sed -n 's/^data: //p' | jq -r '.result.content[0].text' | head -20

Avoid burning the monthly allowance during dev

  • Cache responses in memory or disk while iterating on prompt logic. Birth-data tools are pure functions of their inputs.
  • A complete reading uses 25-40 calls and cannot answer below 20; 300 a month covers seven to twelve complete readings. Plan for a call pack before you script bulk runs. See reading depth and call floors.
  • Failed calls (4xx, 5xx) do not count, so retries during debugging are free.
  • The allowance refreshes on the 1st of each month, UTC.

Get an API key

Sign in at developer.lumin.guru with your email address and the six digit code we send you, then generate a key. Add it as a Bearer header on every call, alongside the Accept header the transport requires:

http
Authorization: Bearer mcp_yourkey...
Accept: application/json, text/event-stream

Self-hosting

Lumin runs as a hosted service. There is no on-prem option today. If your compliance requirements need self-hosting, email contact@lumin.guru to discuss an enterprise arrangement.
PreviousStream responsesNextRecover from errors