What is MCP?
The Model Context Protocol 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.
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.
Setup (Claude Desktop)
Add this to claude_desktop_config.json:
{
"mcpServers": {
"lumina": {
"command": "npx",
"args": ["-y", "@lumina-org/mcp-server"]
}
}
}
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:
claude mcp add lumina -- npx -y @lumina-org/mcp-server
Cursor / Windsurf / Continue
{ "mcpServers": { "lumina": { "command": "npx", "args": ["-y", "@lumina-org/mcp-server"] } } }
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). 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
