# Lumify Guides > Canonical URL: https://lumify.ai/docs/guides.md > HTML twin: https://lumify.ai/docs/guides First-hour REST recipes, then MCP setup and agent resources for building on Lumify. # Guides First-hour REST recipes, then MCP if you are connecting an agent. Copy-paste walkthroughs for odds, intelligence, forecasts, and live scores. > **Tip:** For agents: the machine-readable twin of this page is [/docs/guides.md](/docs/guides.md). For deeper copy-paste recipes see the [agent cookbook](/docs/agent-cookbook.md). ### First hour REST recipes for a first useful result. MCP is below if you are connecting an agent. ## Track live odds movement Two ways to watch a line move without hammering [/v1/events/{id}/odds/history](/docs/reference#event-odds-history) on a tight poll loop: - **Push (recommended):** create a [webhook subscription](/docs/reference#webhooks) with event_types: ["line_move"] and a sport or event_id — you'll get one delivery per event per ingest cycle when a main line's point changes or its price moves by at least 5¢. Transient delivery failures retry automatically; inspect [delivery history](/docs/reference#webhook-deliveries) if a callback looks stuck. - **Pull:** poll [odds history](/docs/reference#event-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. ```bash # 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"], "sport": "nfl"}' ``` ## Pull a full event intelligence report in one call Fetch schedule, odds, and bet intelligence together instead of three separate round trips: ```bash 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](/docs/reference#event-detail) for the full parameter reference. ## Read a forecasted prop wager Scan the daily board, then join live box progress on the same player × market. How + field catalog: [/docs/forecasts](/docs/forecasts). 1. Call list_forecasts (or GET /v1/intelligence/forecasts) with a sport — MLB, NFL, NCAAF, NBA, NCAAB, NHL, or tennis. Rank is conviction. 2. Take event_id and call get_event if you need kickoff, status, or participants. 3. Call get_player_props on that event and match player_id + market for live current, pct_of_line, and settleable. ```bash # 1. Daily board (selected:true rows only) curl "https://lumify.ai/v1/intelligence/forecasts?sport=mlb" \ -H "Authorization: Bearer YOUR_API_KEY" # 2. Live progress for the same event curl "https://lumify.ai/v1/events/9199/player-props" \ -H "Authorization: Bearer YOUR_API_KEY" ``` > **Tip:** forecasts[] on GET /intelligence can populate when available is still false (NBA / NCAAB / NHL, or an MLB/NFL/NCAAF game not yet priced). Do not drop the payload. Worked wager: [/docs/understanding-odds#forecasts](/docs/understanding-odds#forecasts). ## Grade a free-text slip Paste a sentence such as Mets over 5 runs yesterday or Chiefs −3.5 last night. Lumify never guesses a player, team, or event — collisions stay on candidates. The public [/grade](/grade) sheet is 20 free grades a day; an agent should call POST /v1/grade/slip or MCP grade_slip. > **Tip:** Walkthrough + screenshots: [How Lumify grades a slip →](/docs/grade) · Inspector: [POST /v1/grade/slip](/docs/reference#grade-slip) ## 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. > **Tip:** Full walkthrough + finished-product screenshot: [Build a live sports scoreboard with the Lumify API →](/use-cases/live-scoreboard) · Example code: [examples/scoreboard](https://github.com/lumifyai/lumify/tree/main/examples/scoreboard) # 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. > **Note:** Endpoint  https://lumify.ai/mcp Transport  Streamable HTTP (JSON mode, stateless)  · Auth  Bearer API key  · Protocol  2025-06-18 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](/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). [ ![Add Lumify MCP to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg) ](cursor://anysphere.cursor-deeplink/mcp/install?name=lumify&config=eyJ1cmwiOiJodHRwczovL2x1bWlmeS5haS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgWU9VUl9BUElfS0VZIn19) [Get an API key first →](/register) [AI-assisted setup guide →](/docs/ai) The one-click install opens Cursor with a placeholder key — replace YOUR_API_KEY with a key from your [dashboard](/api-keys) before approving. ### Connect from Cursor Recommended (remote): add Lumify to ~/.cursor/mcp.json (or a project-local .cursor/mcp.json): ```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: ```json { "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: ```json { "mcpServers": { "lumify": { "command": "npx", "args": ["-y", "@lumifyai/mcp"], "env": { "LUMIFY_API_KEY": "YOUR_API_KEY" } } } } ``` Alternatively, bridge with mcp-remote: ```json { "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): ```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. | Tool | Description | Credits | | --- | --- | --- | | list_sports | Supported sports with current active season. | 1 | | list_seasons | Seasons per sport/league; optional current-only filter. | 1 | | list_events | Schedule / scores, filterable by sport, league, status, date, season. | 1 | | get_event | Single event; optional include_odds (scoped by bookmaker, default pinnacle) / include_intelligence. | 1 | | batch_get_events | Multiple events by id in one call (max 25). Missing ids cost nothing. | Sum of each event's cost | | query_events | Natural-language event search (e.g. "live nfl games today") — rule-based, mapped to list_events filters. | 1 | | get_live_score | Lightweight live score snapshot. | 1 | | get_odds | Current moneyline / spread / total lines. | 1 (2 for all books) | | get_odds_history | Recorded line-movement history. | 1 (2 for all books) | | get_stats | Raw team/match statistics — sport-specific payload, no scoring. Coverage: [/docs/reference#event-stats](/docs/reference#event-stats). | 1 | | get_player_props | NFL/NCAAF/NBA/NCAAB/NHL/MLB/soccer player-prop mains + live box progress. Sport × market catalog: [/docs/player-props](/docs/player-props). | 1 | | get_team_props | NFL/NCAAF/MLB/soccer team-total mains + this-event team score. | 1 | | get_period_odds | NFL/NCAAF/NBA/NCAAB/soccer first-half, MLB first-five, and tennis first-set mains + period-score settlement. | 1 | | get_splits | Public betting splits (bets% / handle%). | 1 | | get_injuries | Beta late-breaking player injury / availability for an upcoming event. available:false is free. How-to: [/docs/injuries](/docs/injuries). | 0–1 | | get_intelligence | Bet intelligence — probability / Price overlay on MLB, soccer, tennis, NFL, NCAAF; bets[].ev (Beta) on main-line tokens; forecasts[] player-prop and high-confidence main-line (moneyline, spread, total) wagers (same objects as list_forecasts). How + field catalog: [/docs/forecasts](/docs/forecasts). Worked wager: [/docs/understanding-odds#forecasts](/docs/understanding-odds#forecasts). | 1 | | list_ev | Beta main-line EV scan for soccer, MLB, tennis, NFL, and NCAAF. market=h2h\|spreads\|totals (tennis totals 400). Same number as bets[].ev. | 1 | | list_forecasts | Daily board of forecasted wagers — player props (MLB, NCAAF, NFL, NBA, NCAAB, NHL) plus high-confidence main-line picks on tennis, NFL, NCAAF, MLB, and soccer — ranked by conviction. How + field catalog: [/docs/forecasts](/docs/forecasts). Worked wager: [/docs/understanding-odds#forecasts](/docs/understanding-odds#forecasts). | 1 | | list_teams | Team directory with sport/league/conference filters. | 1 | | get_team | Single team profile with home venue. | 1 | | search_players | Player identity search by name, sport, country, ranking. Tennis standings nest under rankings. | 1 | | get_player | Single player identity profile. | 1 | | get_player_events | A player's schedule / results (±30 days by default). | 1 | | resolve_player | Map a messy player name plus sport/team/event clues to a Lumify player_id. Returns ambiguous instead of guessing. | 1 | | resolve_team | Map a messy team string plus sport/league/event clues to a Lumify team_id. Returns ambiguous instead of guessing. | 1 | | resolve_event | Map an event_id, or a player/team clue plus a date window, to a Lumify event_id. Returns ambiguous instead of guessing. | 1 | | grade_slip | Grade settleable player-prop legs (nfl/nba/ncaaf/ncaab/nhl/mlb/soccer), structured and free-text game markets (h2h / spreads / totals), and team_total on nfl/ncaaf/mlb/soccer. Structured event_id preferred; player_id is required on props and forbidden on game keys; team_id is required on team_total. Free-text grades only when team/player and event resolve uniquely — a bare Over 47.5 stays unmapped. Ambiguous team/event binds stay on team_resolve / event_resolve. | 1 | | estimate_cost | Pre-call credit-cost estimate (min–max range) for one or more planned tool calls. | Free | ### 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). > **Warning:** Web connectors (ChatGPT / Claude.ai): browser-based connectors require OAuth, which Lumify's key-based MCP server does not implement yet. Use Cursor, Claude Desktop (via npx @lumifyai/mcp), or any client that supports Bearer-token headers. > **Tip:** Building with AI? See the [AI-assisted development guide](/docs/ai) for Cursor/Claude prompts, llms.txt, OpenAPI, and copy-paste agent recipes. ## Cookbook & Postman Deeper, copy-paste-ready references for building on Lumify: | Resource | Description | | --- | --- | | [Agent cookbook](/docs/agent-cookbook.md) | End-to-end recipes for REST + MCP, including verified client configs and billing behaviour. | | [Postman collection](/docs/lumify.postman_collection.json) | Importable collection covering the REST endpoints and MCP JSON-RPC calls. | | [llms.txt](/llms.txt) | Compact machine-readable overview for LLM agents. | | [agent.json](/.well-known/agent.json) | Agent manifest with the MCP endpoint and transport. | | [OpenAPI schema](/openapi.json) | Full machine-readable spec for the REST surface. | ## 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](#mcp) 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](#mcp) 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. > **Tip:** Prefer REST? The equivalent call is [GET /v1/events/{id}/splits](/docs/reference#event-splits) — MCP and REST share the same billing and rate limits. ## 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: ```bash # 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](/docs/reference#agent-keys) and [Credits & credit packs](/docs/reference#agent-credits).