> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumina-org.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect any MCP client (Claude Desktop, Cursor, Windsurf, Continue) to Lumina and buy a policy in one sentence.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard
that lets AI assistants connect to external tools and data. The **official Lumina
MCP server** (`@lumina-org/mcp-server`) exposes the protocol as MCP **tools**,
**resources**, and **prompts** — so any MCP client can browse products, quote
premiums, and **buy a policy in one sentence**.

## Why Lumina ships an MCP server

Lumina is agent-first. One MCP server reaches every MCP-capable client at once
(Claude Desktop, Cursor, Windsurf, Continue, …). The default purchase path is the
**sandbox** — a real on-chain policy with **no wallet, no gas, and no API key**.

<Note>
  The server **never holds a private key**. Write actions (`buy_policy_real`,
  `redeem_bond`, `marketplace_*`) return an **unsigned transaction** for your
  wallet/agent to sign. The sandbox path needs no wallet at all.
</Note>

## Setup (Claude Desktop)

Add this to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "lumina": {
      "command": "npx",
      "args": ["-y", "@lumina-org/mcp-server"]
    }
  }
}
```

Restart Claude Desktop, then ask: *"Use Lumina to buy a FLASHBTC1H policy."*

**Where is `claude_desktop_config.json`?**

| OS      | Path                                                              |
| ------- | ----------------------------------------------------------------- |
| macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json`                     |
| Linux   | `~/.config/Claude/claude_desktop_config.json`                     |

### Claude Code (CLI)

One command — no config file needed:

```bash theme={null}
claude mcp add lumina -- npx -y @lumina-org/mcp-server
```

Then in any Claude Code session: *"Use Lumina to quote a \$100 FLASHBTC1H policy."*

### Cursor / Windsurf / Continue

```json theme={null}
{ "mcpServers": { "lumina": { "command": "npx", "args": ["-y", "@lumina-org/mcp-server"] } } }
```

(Continue uses `experimental.modelContextProtocolServers` with a `stdio` transport.)

### Optional env

| Var                                                      | Purpose                                             |
| -------------------------------------------------------- | --------------------------------------------------- |
| `LUMINA_API_KEY`                                         | `lk_…` key for wallet-scoped reads (policies/bonds) |
| `LUMINA_API_BASE` / `LUMINA_CHAIN_ID` / `LUMINA_RPC_URL` | point at a different deployment                     |

## What it exposes

**Tools (11):** `browse_products`, `quote_policy`, `buy_policy_sandbox`,
`buy_policy_real`, `get_policy_status`, `get_bond_balance`, `redeem_bond`,
`marketplace_list`, `marketplace_buy`, `watch_triggers`, `get_protocol_stats`.

**Resources (4):** `lumina://products`, `lumina://stats`,
`lumina://policies/{wallet}`, `lumina://bonds/{wallet}`.

**Prompts (3):** `first_policy`, `compare_products`, `monitor_portfolio`.

## Use cases

* **One-sentence purchase:** "Buy me flash-crash cover on BTC for the next hour."
* **Portfolio monitoring:** the `monitor_portfolio` prompt summarizes policies,
  bonds, and approaching triggers for a wallet.
* **Self-signed flows:** `buy_policy_real` / `redeem_bond` return unsigned txs your
  agent signs with its own wallet — keys never leave the client.

## Try these prompts

Once connected, paste any of these into your assistant:

* *"Browse Lumina products."*
* *"Buy a FLASHBTC1H policy in sandbox."*  (no wallet, no gas)
* *"Show my bonds for 0x…"*
* *"Compare FLASHBTC1H vs FLASHBTC24-001 and recommend one for a short hedge."*

## Troubleshooting

| Symptom                                 | Fix                                                                                                                                                  |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npx: command not found`                | Install **Node.js 18+** (which ships `npx`), then restart your client.                                                                               |
| Server doesn't respond / fails to start | Check your `claude_desktop_config.json` (or client config) is **valid JSON** — a trailing comma or missing brace is the usual culprit.               |
| Tools not visible after editing config  | **Fully quit and reopen** the app (not just close the window) so it re-reads the MCP config.                                                         |
| `401` on `get_bond_balance` / policies  | Those reads are wallet-scoped — set `LUMINA_API_KEY` ([get one](https://www.lumina-org.com/app/agent/api-keys)). Sandbox/quote/products need no key. |

## FAQ

**Do I need a wallet?** No — `buy_policy_sandbox` purchases against Lumina's relayer wallet.

**Does it cost gas?** No for the sandbox path (the relayer pays). Self-signed
`buy_policy_real` / `redeem_bond` cost gas on your own wallet.

**Does it work offline?** No — the tools call the live Lumina API and Base RPC.

**Which apps support MCP?** Claude Desktop, Cursor, Windsurf, Continue, and Claude
Code (CLI) — plus any other MCP-compatible client.

**Will it touch real funds?** No — Lumina is on Base mainnet with mock USDC.

## Links

* Package: [`@lumina-org/mcp-server`](https://www.npmjs.com/package/@lumina-org/mcp-server)
* Source: [github.com/org-lumina/lumina-mcp](https://github.com/org-lumina/lumina-mcp)
* MCP spec: [modelcontextprotocol.io](https://modelcontextprotocol.io)