# Set up Lumin

You are an agent setting up Lumin for the person you are working with. Lumin
is an astrology MCP server: 315 tools across KP, Parashari,
Jaimini and Tajik, and every result carries the rule it applied and where
that rule comes from.

MCP endpoint: https://mcp.lumin.guru/mcp
Transport: Streamable HTTP. Sign in with OAuth, or send a Lumin API key.

## Rules

- Never guess birth details. Ask for the date, the local clock time and the
  place. A few minutes of birth time can change the chart. If the person does
  not know their birth time, leave it out and say a rectification can narrow
  it later.
- You cannot sign in for the person. Sign in is their email address and a six
  digit code Lumin sends them. Tell them when it is their turn.
- Never commit, log or print an API key.
- Every account gets 300 tool calls a month free, with no card. Say so if the
  person asks what it costs.

## Step 1. Work out where you are running

Pick the section that matches, and follow only that one.

### Claude Code

You can run the install yourself.

1. Run: `claude plugin marketplace add https://www.lumin.guru/plugin/marketplace.json`
2. Ask for the name the chart goes under, the birth date, the birth time and
   the birth place.
3. Run:
   `claude plugin install lumin@lumin --config birth_name="<name>" --config birth_date="<YYYY-MM-DD>" --config birth_time="<HH:MM, 24 hour local clock>" --config birth_place="<city, country>"`
4. Tell the person the steps left, which only they can do: restart Claude
   Code, run `/mcp`, pick `lumin` and sign in, then run `/lumin:status`.

If the person wants the tools without the plugin, run
`claude mcp add --transport http lumin https://mcp.lumin.guru/mcp` instead. The plugin
is better: it adds the reading method and enforces the tool-call floor.

### Claude on the web or desktop

You cannot add a connector here. Tell the person to do it:

1. Open Settings, then Connectors.
2. Click Add custom connector, name it Lumin, paste https://mcp.lumin.guru/mcp.
3. Click Connect and sign in with their email address and the code.

Once they say it is connected, check it: call `get_reading_protocol` and
confirm it returned, without repeating it. Then ask for their birth details
and call `set_birth_profile`, working out latitude, longitude and the UTC
offset at birth from the place and date. Read back what it accepted in one
line so they can catch a mistake.

### Cursor

Write this to `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json`
for every project. Cursor opens the sign in page on first use.

```json
{
  "mcpServers": {
    "lumin": {
      "url": "https://mcp.lumin.guru/mcp"
    }
  }
}
```

### VS Code

Write this to `.vscode/mcp.json`.

```json
{
  "servers": {
    "lumin": {
      "type": "http",
      "url": "https://mcp.lumin.guru/mcp"
    }
  }
}
```

### A client without OAuth

Ask the person for a Lumin API key. It starts with `mcp_` and they create
it at https://app.lumin.guru/api-keys. Put it in the client's secret store or an
environment variable, never in a committed file.

```json
{
  "mcpServers": {
    "lumin": {
      "url": "https://mcp.lumin.guru/mcp",
      "headers": {
        "Authorization": "Bearer mcp_your_key"
      }
    }
  }
}
```

### A codebase that will call Lumin

1. Add `LUMIN_API_KEY` to the env example file and ask for the key.
2. Connect with the language's official MCP SDK over Streamable HTTP to
   https://mcp.lumin.guru/mcp, header `Authorization: Bearer <LUMIN_API_KEY>`.
3. Raw HTTP needs `Accept: application/json, text/event-stream` on every
   POST, or the server answers 406. Responses arrive as an SSE stream.
4. Call `tools/list`, then `set_birth_profile` with a test chart and a
   question, and show the person the reading plan it returns.
5. Keep the rule and source fields on every result. Do not strip them.
6. Ask before choosing which tools the product calls.

Guides: https://docs.lumin.guru/build/quickstart and https://docs.lumin.guru/build/guides/integrate-into-your-app

## Step 2. Reading, once connected

Call `set_birth_profile` first for every question, passing the question. It
returns the numbered tool list and the minimum number of calls. If your
server instructions look cut short, call `get_reading_protocol`.

- Full reading: minimum 20 tool calls, expected 25 to 40.
- Focused question: minimum 12 tool calls, expected 15 to 20.
- Factual lookup: minimum 5 tool calls, expected 5 to 8.
- Nothing that touches a birth chart is answered in fewer than 5 calls.

## More

- Every page and tool: https://docs.lumin.guru/llms.txt
- Example questions: https://docs.lumin.guru/use/examples
- Support: contact@lumin.guru