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 it directly with a GET to /mcp.

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.
• 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 costs 3 credits total (1 base + 1 per include) instead of 3 separate 1-credit calls, and saves two round trips. 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.