MCP Server Setup

The Model Context Protocol (MCP) allows LLMs and AI agents to connect directly to external data sources. By connecting to our MCP server, your AI tools gain access to comprehensive horse racing data including racecards, results, form analysis, jockey and trainer statistics, and more.

Once connected, your AI tools can seamlessly interact with the API to provide horse racing information and insights, as well as gaining an improved understanding of coding and development with the API.

Server URL
https://mcp.theracingapi.com

Authentication

You'll need your Racing API credentials to connect. You can find your username and password in the dashboard under My Account after subscribing to a plan.

Web interfaces (claude.ai, chatgpt.com, grok.com, gemini.google.com) use OAuth — you'll be redirected to a login page to enter your credentials. CLIs and APIs authenticate via HTTP headers included in your configuration.

OAuth sessions expire after 30 days of inactivity. If no requests are made to the MCP server within that period, you'll need to reconnect and log in again.

Select your AI platform for setup instructions:

Web & Desktop App

Requires Free, Pro, Max, Team, or Enterprise plan

These steps work for both claude.ai and the Claude Desktop app.

  1. Open Customize from the main menu in Claude
  2. Select the Connectors tab
  3. Click the + button, then Add custom connector
  4. Enter the connector name: The Racing API
  5. Enter the MCP server URL:
    https://mcp.theracingapi.com
  6. Click Add then click Connect once The Racing API appears in the Connectors list — you will be redirected to a login page where you can enter your Racing API username and password
  7. Once authenticated, The Racing API tools will be available in your conversations

Team & Enterprise plans: an organisation Owner may need to add the connector first under Organization settings > Connectors before members can connect to it from Customize > Connectors.

Recommended model: Opus 5 with medium or high effort offers the best balance of speed and intelligence for racing data queries.

Claude Code (CLI)

Run the following command in your terminal, replacing the placeholder values with your API credentials:

Terminal 
claude mcp add --transport http \
  the-racing-api \
  https://mcp.theracingapi.com/ \
  --header "X-RacingAPI-Username: YOUR_USERNAME" \
  --header "X-RacingAPI-Password: YOUR_PASSWORD"

API (Messages API)

Requires anthropic-beta: mcp-client-2025-11-20 header

Connect to the MCP server programmatically using the Messages API, replacing the placeholder values with your API credentials:

JSON Request Body 
{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "What are today's racecards?"
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.theracingapi.com/",
      "name": "the-racing-api",
      "authorization_token": "YOUR_OAUTH_ACCESS_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "the-racing-api"
    }
  ]
}

Authentication: The Messages API uses OAuth. Obtain an access token by running npx @modelcontextprotocol/inspector, connecting to https://mcp.theracingapi.com/, and completing the OAuth flow. Pass the resulting token as authorization_token. The API does not handle token refresh automatically — you are responsible for tracking expiry and using your refresh token to obtain a new access token when it expires.

References: Custom connectors using remote MCP • MCP — Claude Code • MCP Connector — Claude API

Web Interface (chatgpt.com)

Requires a paid plan (Plus, Pro, Business, Enterprise, or Edu)
  1. Go to Settings > Security and login and enable Developer mode
  2. Open the Plugins page and click the + button
  3. Enter the name as 'The Racing API'
  4. Under Connection, enter the MCP Server URL:
    https://mcp.theracingapi.com
  5. Ensure Authentication is set to OAuth
  6. Create the connection — you will be redirected to a login page — enter your Racing API username and password to authorize the connection
  7. Once authenticated, The Racing API tools will be available in your conversations

Business, Enterprise & Edu plans: a workspace admin may need to allow developer mode under Workspace Settings > Permissions & Roles.

API (Responses API)

Connect to the MCP server programmatically using the Responses API, replacing the placeholder values with your API credentials:

JSON Request Body 
{
  "model": "gpt-5.6",
  "tools": [
    {
      "type": "mcp",
      "server_label": "the-racing-api",
      "server_url": "https://mcp.theracingapi.com/",
      "headers": {
        "X-RacingAPI-Username": "YOUR_USERNAME",
        "X-RacingAPI-Password": "YOUR_PASSWORD"
      },
      "require_approval": "never"
    }
  ],
  "input": "What are today's racecards?"
}

Codex (CLI)

Add the following to your Codex configuration file, replacing the placeholder values with your API credentials:

~/.codex/config.toml 
[mcp_servers.the-racing-api]
url = "https://mcp.theracingapi.com/"

[mcp_servers.the-racing-api.http_headers]
X-RacingAPI-Username = "YOUR_USERNAME"
X-RacingAPI-Password = "YOUR_PASSWORD"

References: Developer mode — ChatGPT • MCP and Connectors — OpenAI API • MCP Servers — Codex

Web Interface (gemini.google.com)

Gemini Spark only — personal Google accounts in the US

Custom MCP connectors are supported in Gemini Spark, the Gemini app's agentic mode. They are not available in regular Gemini chat.

  1. Go to Settings & help > Connected apps in the Gemini web app
  2. Add a custom app and enter the MCP server URL:
    https://mcp.theracingapi.com
  3. Complete the OAuth flow — you will be redirected to a login page where you can enter your Racing API username and password
  4. Once connected, The Racing API tools will be available in Gemini Spark conversations

Gemini CLI

Run the following command in your terminal, replacing the placeholder values with your API credentials:

Terminal 
gemini mcp add --transport http \
  the-racing-api \
  https://mcp.theracingapi.com/ \
  --header "X-RacingAPI-Username: YOUR_USERNAME" \
  --header "X-RacingAPI-Password: YOUR_PASSWORD"

Alternatively, add the following to your Gemini CLI settings file:

~/.gemini/settings.json 
{
  "mcpServers": {
    "the-racing-api": {
      "httpUrl": "https://mcp.theracingapi.com/",
      "headers": {
        "X-RacingAPI-Username": "YOUR_USERNAME",
        "X-RacingAPI-Password": "YOUR_PASSWORD"
      }
    }
  }
}

References: Connect custom apps for Gemini Spark • MCP servers with the Gemini CLI

Web Interface (grok.com)

  1. Go to grok.com/connectors
  2. Click New Connector, then select Custom
  3. Enter the MCP server URL:
    https://mcp.theracingapi.com
  4. Complete the authentication flow — you will be redirected to a login page where you can enter your Racing API username and password
  5. Once connected, The Racing API tools will be available in your conversations

Business & Enterprise plans: a team admin may need to provision the connector via console.x.ai > Grok Business > Connectors.

xAI API

Connect to the MCP server via the xAI API, replacing the placeholder values with your API credentials:

JSON Request Body 
{
  "model": "grok-4.5",
  "tools": [
    {
      "type": "mcp",
      "server_label": "the-racing-api",
      "server_url": "https://mcp.theracingapi.com/",
      "headers": {
        "X-RacingAPI-Username": "YOUR_USERNAME",
        "X-RacingAPI-Password": "YOUR_PASSWORD"
      }
    }
  ],
  "input": [
    {
      "role": "user",
      "content": "What are today's racecards?"
    }
  ]
}

References: Connectors — Grok • Remote MCP Tools — xAI API

Lovable App

  1. Open Connectors in the Lovable dashboard
  2. Scroll to the bottom of the All view and select the Custom card labelled MCP
  3. Enter the server name: The Racing API
  4. Enter the server URL:
    https://mcp.theracingapi.com
  5. Ensure the authentication method is set to OAuth
  6. Click Add & authorize — you will be redirected to a login page where you can enter your Racing API username and password
  7. Once authorized, The Racing API tools will be available as contextual data for the Lovable Agent

Note: MCP connectors act as chat connectors — they provide contextual data while building, but cannot be used inside your published app. To use racing data in a published app, call the REST API directly.

Reference: Connect a custom MCP server — Lovable Docs

Web Interface (perplexity.ai)

Requires Pro, Max, or Enterprise plan
  1. Go to Settings > Connectors
  2. Add a custom remote connector
  3. Enter the connector name: The Racing API
  4. Enter the MCP server URL:
    https://mcp.theracingapi.com
  5. Select the Streamable HTTP transport and set authentication to OAuth 2.0
  6. Save the connector — you will be redirected to a login page where you can enter your Racing API username and password
  7. Once authenticated, The Racing API tools will be available in your conversations

Reference: Adding custom remote connectors — Perplexity Help Center

Cursor

Add the following to your Cursor MCP configuration file, replacing the placeholder values with your API credentials. Use ~/.cursor/mcp.json to make the server available in all projects, or .cursor/mcp.json inside a project for that project only:

~/.cursor/mcp.json 
{
  "mcpServers": {
    "the-racing-api": {
      "url": "https://mcp.theracingapi.com/",
      "headers": {
        "X-RacingAPI-Username": "YOUR_USERNAME",
        "X-RacingAPI-Password": "YOUR_PASSWORD"
      }
    }
  }
}

You can also manage MCP servers from Settings > Tools & MCP within Cursor. Once the server shows as connected, The Racing API tools will be available to the agent.

Reference: MCP — Cursor Docs

VS Code (GitHub Copilot)

Requires GitHub Copilot (free tier available)

Open the Command Palette (Cmd/Ctrl+Shift+P), run MCP: Add Server, choose HTTP, and enter the server URL. Alternatively, add the following to your MCP configuration file, replacing the placeholder values with your API credentials:

.vscode/mcp.json 
{
  "servers": {
    "the-racing-api": {
      "type": "http",
      "url": "https://mcp.theracingapi.com/",
      "headers": {
        "X-RacingAPI-Username": "YOUR_USERNAME",
        "X-RacingAPI-Password": "YOUR_PASSWORD"
      }
    }
  }
}

Once added, The Racing API tools will be available in Copilot agent mode via the Tools picker in the Chat view.

Reference: MCP servers — VS Code Docs