SDK

MCP Server

racehooks-mcp is a Model Context Protocol server that gives AI assistants — Claude, Cursor, Windsurf — direct access to your RaceHooks account. Ask Claude to create webhooks, start simulations, check delivery health, or set up a fantasy scoring integration without leaving your AI chat window. The MCP server surfaces all sports and feeds available on your account — as RaceHooks expands to IndyCar and NASCAR, the same tools cover the new data.

Claude DesktopClaude CodeCursorWindsurf

How it works

The MCP server runs as a local stdio process — it never binds a network port and your credentials never leave your machine. It exposes 13 tools, 4 live resources, and 3 guided prompts to any MCP-compatible client. Token refresh is handled automatically.

Installation

bash

npm install -g racehooks-mcp

Or run directly without installing:

bash

npx racehooks-mcp

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the Windows equivalent:

claude_desktop_config.json

{
  "mcpServers": {
    "racehooks": {
      "command": "npx",
      "args": ["-y", "racehooks-mcp"],
      "env": {
        "RACEHOOKS_CLIENT_ID":     "your-client-id",
        "RACEHOOKS_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Code

.claude/settings.json

// .claude/settings.json — project-level (after `npm i -g racehooks-mcp`)
{
  "mcpServers": {
    "racehooks": {
      "type":    "stdio",
      "command": "racehooks-mcp",
      "env": {
        "RACEHOOKS_CLIENT_ID":     "your-client-id",
        "RACEHOOKS_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Cursor / Windsurf

.cursor/mcp.json

// .cursor/mcp.json
{
  "mcpServers": {
    "racehooks": {
      "command": "npx",
      "args": ["-y", "racehooks-mcp"],
      "env": {
        "RACEHOOKS_CLIENT_ID":     "your-client-id",
        "RACEHOOKS_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

✦

Your RACEHOOKS_CLIENT_ID and RACEHOOKS_CLIENT_SECRET are on the API Keys page.

Example prompts

>Check my RaceHooks account health

>Create a raceevent webhook for https://myapp.com/hook, filtering for Ferrari only

>Start a simulation of the 2025 Monaco GP qualifying at 10× speed

>Show me which feeds are using the most delivery quota today

>Set up a fantasy scoring webhook for my VER, NOR, LEC team at https://scoring.myapp.com/hook

>List all my webhooks and tell me which ones are paused

Tools

All tool inputs are validated with Zod schemas that Claude uses to generate high-quality arguments.

ToolDescription

list_feedsReturn the full feed catalog with availability tiers.

list_webhooksReturn all webhook subscriptions on this account.

get_webhookReturn a single webhook by ID with its filter configuration.

create_webhookCreate a new webhook with optional driver/constructor/position filters.

delete_webhookDelete a webhook by ID.

test_webhookSend a test delivery to a webhook and return the result.

get_webhook_logsReturn recent delivery logs for a webhook.

get_live_sessionReturn current live session state: flag, lap, driver positions.

list_eventsReturn the race calendar with session dates for all supported sports.

get_subscriptionReturn current tier, plan limits, and usage snapshot.

get_usageReturn today's delivery count, failure count, and remaining limit.

get_usage_by_feedReturn delivery counts broken down by feed.

get_billing_planReturn detailed billing plan with beta status and Stripe period.

start_simulationStart a replay of a historical session at chosen speed.

list_simulationsList all simulations (running and completed).

get_simulationReturn status and logs for a specific simulation.

cancel_simulationCancel a running simulation.

Resources

Resources are read-only named contexts the AI loads into its reasoning window without you having to ask. They stay fresh because they are fetched live on each request.

racehooks://feedsComplete feed catalog with tier requirements — loaded into context automatically.

racehooks://liveCurrent live session: flag status, lap counter, full driver standings with tyre compounds.

racehooks://webhooksAll active webhook subscriptions including filter configurations.

racehooks://usageCurrent delivery usage: total today, failure count, daily limit, remaining capacity.

Guided prompts

Prompts are slash-command–style workflows in supporting clients (Claude Desktop, Claude Code). They accept parameters and generate a complete conversational setup sequence.

setup_race_event_webhookGuided workflow: create a raceevent webhook with optional driver, constructor, or position filters. Claude collects your endpoint URL and preferences, then creates and tests the webhook.

setup_fantasy_scoring_webhookGuided workflow: create a webhook for a fantasy scoring engine. Accepts your driver list (TLAs) and registers a raceevent webhook filtered to those drivers.

check_account_healthFull account health summary: calls get_subscription, get_usage_by_feed, list_webhooks, and get_live_session in parallel, then summarises tier, delivery budget, webhook status, and live session state.

Security

ℹ

The MCP server runs as a local stdio process — it never binds a network port. Your credentials are passed via environment variables and are never included in tool call arguments or resource URIs. All diagnostic output goes to stderr to avoid corrupting the JSON-RPC channel.

← Node.js SDK Analytics →