Guides

Model Context Protocol (MCP)

Lumify runs a hosted MCP server so AI agents can call the entire sports-intelligence API as native tools — no wrapper code required.

Any MCP-compatible client connects by pointing at https://lumify.ai/mcp and passing your Lumify API key as a Bearer token. The server is fully self-describing — a client's tools/list call returns the current tool catalogue with input schemas. You can inspect the discovery document with a browser GET to /mcp (JSON). Tool calls use POST only — Lumify does not offer a GET Server-Sent Events stream on this URL. Some clients briefly probe with Accept: text/event-stream and receive 405 Allow: POST; that is expected transport negotiation, then they continue over POST JSON (streamable HTTP).

Get an API key first → AI-assisted setup guide →

The one-click install opens Cursor with a placeholder key — replace YOUR_API_KEY with a key from your dashboard before approving.

Connect from Cursor

Recommended (remote): add Lumify to ~/.cursor/mcp.json (or a project-local .cursor/mcp.json):

{
  "mcpServers": {
    "lumify": {
      "url": "https://lumify.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Stdio bridge (optional): if you prefer a local process, use the published @lumifyai/mcp package:

{
  "mcpServers": {
    "lumify": {
      "command": "npx",
      "args": ["-y", "@lumifyai/mcp"],
      "env": { "LUMIFY_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Connect from Claude Desktop

Claude Desktop speaks stdio. Prefer the official bridge package:

{
  "mcpServers": {
    "lumify": {
      "command": "npx",
      "args": ["-y", "@lumifyai/mcp"],
      "env": { "LUMIFY_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Alternatively, bridge with mcp-remote:

{
  "mcpServers": {
    "lumify": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://lumify.ai/mcp",
        "--header", "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

Connect from VS Code / Copilot

Add a server entry under mcp.servers in your VS Code settings (or .vscode/mcp.json):

{
  "servers": {
    "lumify": {
      "type": "http",
      "url": "https://lumify.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Available tools

Each tool maps 1:1 to a REST endpoint and returns identical data. Credit cost mirrors the equivalent REST call.

Billing

The MCP handshake is free: initialize, tools/list, and ping never cost credits. Only tools/call is metered, at the same rate as the matching REST endpoint. Each result reports its cost under _meta.credits_used. Calls that return no usable data because it isn't available yet — odds, line history, splits, or intelligence for a match that hasn't been priced/computed — are free (_meta.credits_used: 0).

Cookbook & Postman

Deeper, copy-paste-ready references for building on Lumify:

Track live odds movement

Two ways to watch a line move without hammering /v1/events/{id}/odds/history on a tight poll loop:

• Push (recommended): create a webhook subscription with event_types: ["line_move"] — you'll be notified the moment a price or point changes. Transient delivery failures retry automatically; inspect delivery history if a callback looks stuck.
• Pull: poll odds history every few minutes and diff against the last recorded_at you've seen. History is not cached, so every call reflects the latest ingest.

# Subscribe once — deliveries arrive at your endpoint from then on
curl -X POST https://lumify.ai/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/lumify", "event_types": ["line_move"]}'

Build an MCP betting-splits agent

Give an LLM agent read access to public betting splits with no REST wrapper code — connect to the hosted MCP server and call its tools directly:

1. Connect Cursor, Claude Desktop, or any MCP client to https://lumify.ai/mcp with your API key as the Bearer token (see the MCP section for client configs).
2. Call the list_events tool filtered by sport/date to find event IDs.
3. Call the get_splits tool per event ID — the agent reasons over bets%/handle% directly, no JSON parsing code required.

Pull a full event intelligence report in one call

Fetch schedule, odds, and bet intelligence together instead of three separate round trips:

curl "https://lumify.ai/v1/events/4812?include_odds=true&include_intelligence=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

This is still 1 credit and saves two round trips versus separate event, odds, and intelligence calls. See Get an event for the full parameter reference.

Provision API access programmatically

Let an agent onboard itself — mint a key, check its balance, and top up credits — without a human touching the dashboard:

# 1. Mint a key (needs an existing session or key to bootstrap)
curl -X POST https://lumify.ai/api/agent/keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "agent-worker-1"}'

# 2. Check balance before a big batch of calls
curl https://lumify.ai/api/agent/credits \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. Top up if running low
curl -X POST https://lumify.ai/api/agent/credits/topup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pack_id": 1}'

Full parameter and error reference: Manage API keys and Credits & credit packs.

Build a live sports scoreboard

Discover in-progress games with GET /v1/events?status=inprogress, stream score updates over SSE, and render a live board — with a cloneable open-source demo.