AI Researcher MCP

Intro

Take full advantage of the AI Researcher stack with its MCP Server, from Q&A, Content Creation, Streaming, and everything in-between, including the full data set.

Follow the below instructions to get up and running.

Prerequisites

Before connecting to the AI Researcher MCP Server, you will need:

A Sportradar Marketplace account and corresponding API key
An active product subscription

Your Marketplace API key will be used to authenticate all MCP requests via the x-api-key header.

🔐
Access
Locate your API key in your Sportradar Marketplace account.

Step 1: Initialize a Session

All MCP interactions are session-based. The first request must use the initialize method, which registers your client and returns a mcp-session-id that you include on every subsequent request.

The production MCP URL is https://api.sportradar.com/ai-researcher/{league}/mcp

Supported Leagues

Value	League
`mlb`	Major League Baseball
`nba`	National Basketball Association
`nfl`	National Football League
`ncaafb`	NCAA Football
`ncaamb`	NCAA Men's Basketball
`nhl`	National Hockey League

Request

curl -i -X POST "https://api.sportradar.com/ai-researcher/{league}/mcp" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "id": 1,
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {
        "roots": { "listChanged": true },
        "sampling": {}
      },
      "clientInfo": {
        "name": "my-app",
        "version": "1.0.0"
      }
    }
  }'

Response

The response headers will contain mcp-session-id:

HTTP/2 200
Content-Type: text/event-stream
mcp-session-id: 550e8400-e29b-41d4-a716-446655440000

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{...},"serverInfo":{"name":"maven-mcp-server","version":"1.0.0"}}}

Save the mcp-session-id — it is required for all further requests in this session.

Step 2: List Available Tools

With an active session, you can discover what the server can do by requesting its tool list.

Request

curl -X POST "https://api.sportradar.com/ai-researcher/{league}/mcp" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -H "mcp-protocol-version: 2025-06-18" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 2
  }'

Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "ask-question",
        "description": "Ask a question about sports data. This tool queries sports databases and uses AI to provide accurate answers about games, schedules, players, teams, and statistics.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "question": {
              "type": "string",
              "description": "The sports data question to answer"
            },
            "league": {
              "type": "string",
              "enum": ["mlb", "nba", "nfl", "ncaafb", "ncaamb", "nhl"],
              "description": "The sports league"
            },
            "context": {
              "description": "Optional structured context to provide with the question"
            }
          },
          "required": ["question", "league"]
        }
      }
    ]
  }
}

The server currently exposes one tool: ask-question.

Step 3: Ask Your First Question

Now you are ready to query sports data. Call the ask-question tool with a natural-language question and the relevant league.

Request

curl -X POST "https://api.sportradar.com/ai-researcher/{league}/mcp" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -H "mcp-protocol-version: 2025-06-18" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 3,
    "params": {
      "name": "ask-question",
      "arguments": {
        "question": "Who are the active leaders in leadoff home runs?",
        "league": "mlb"
      }
    }
  }'

curl -X POST "https://api.sportradar.com/ai-researcher/{league}/mcp" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -H "mcp-protocol-version: 2025-06-18" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 3,
    "params": {
      "name": "ask-question",
      "arguments": {
        "question": "Who led the league in passing yards last season?",
        "league": "nfl"
      }
    }
  }'

Response

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"019edde9-aeb4-7078-9e2e-8e107dc05d99\",\"metadata\":{\"league\":\"MLB\"},\"artifacts\":[ ... ],\"message\":{ ... }}"
      }
    ],
    "structuredContent": {
      "id": "019edde9-aeb4-7078-9e2e-8e107dc05d99",
      "metadata": {
        "league": "MLB"
      },
      "artifacts": [
        {
          "type": "table",
          "name": "Leadoff HR Leaders",
          "content": {
            "title": "Leadoff HR Leaders",
            "data": [
              { "Player": "George Springer", "Team": "Toronto Blue Jays", "HR": 65 },
              { "Player": "Mookie Betts", "Team": "Los Angeles Dodgers", "HR": 52 },
              { "Player": "Kyle Schwarber", "Team": "Washington Nationals", "HR": 46 },
              { "Player": "Jose Altuve", "Team": "Houston Astros", "HR": 42 },
              { "Player": "Ronald Acuna Jr.", "Team": "Atlanta Braves", "HR": 39 },
              { "Player": "Francisco Lindor", "Team": "New York Mets", "HR": 32 },
              { "Player": "Marcus Semien", "Team": "Toronto Blue Jays", "HR": 31 },
              { "Player": "Shohei Ohtani", "Team": "Los Angeles Dodgers", "HR": 29 },
              { "Player": "Joc Pederson", "Team": "Texas Rangers", "HR": 27 },
              { "Player": "Byron Buxton", "Team": "Minnesota Twins", "HR": 26 },
              { "Player": "Yandy Díaz", "Team": "Tampa Bay Rays", "HR": 25 },
              { "Player": "Andrew McCutchen", "Team": "San Francisco Giants", "HR": 25 },
              { "Player": "Trea Turner", "Team": "Washington Nationals", "HR": 20 },
              { "Player": "Cedric Mullins", "Team": "Baltimore Orioles", "HR": 18 },
              { "Player": "J.P. Crawford", "Team": "Seattle Mariners", "HR": 17 },
              { "Player": "Brandon Nimmo", "Team": "Texas Rangers", "HR": 16 },
              { "Player": "Fernando Tatis Jr.", "Team": "San Diego Padres", "HR": 16 },
              { "Player": "Ketel Marte", "Team": "Arizona Diamondbacks", "HR": 15 },
              { "Player": "Enrique Hernández", "Team": "Los Angeles Dodgers", "HR": 14 },
              { "Player": "Gunnar Henderson", "Team": "Baltimore Orioles", "HR": 13 },
              { "Player": "Zach Neto", "Team": "Los Angeles Angels", "HR": 13 },
              { "Player": "CJ Abrams", "Team": "Washington Nationals", "HR": 12 },
              { "Player": "Adam Frazier", "Team": "San Diego Padres", "HR": 12 },
              { "Player": "Jonathan India", "Team": "Kansas City Royals", "HR": 12 },
              { "Player": "Jarren Duran", "Team": "Boston Red Sox", "HR": 11 }
            ],
            "metadata": {
              "columns": [
                {
                  "title": "Player",
                  "key": "Player",
                  "description": "Player Name",
                  "cutoff_year": 1876
                },
                {
                  "title": "Team",
                  "key": "Team",
                  "description": "Team Name",
                  "cutoff_year": 1876
                },
                {
                  "title": "HR",
                  "key": "HR",
                  "description": "Leadoff Home Runs",
                  "sort_direction": "DESC",
                  "cutoff_year": 1876
                }
              ],
              "filter_column_cutoffs": [
                {
                  "column_name": "context_season_type",
                  "label": "REG",
                  "display_name": "Season Type",
                  "cutoff_year": 1876
                },
                {
                  "column_name": "context_player_id",
                  "label": "Active",
                  "display_name": "Player",
                  "cutoff_year": 1876
                }
              ]
            }
          }
        }
      ],
      "message": {
        "role": "assistant",
        "content": "Here are the top 25 active leaders in career regular-season leadoff home runs (first PA of game, batting 1st in the 1st inning with score tied 0-0):"
      }
    }
  },
  "jsonrpc": "2.0",
  "id": 3
}

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"019edde9-aeb4-7078-9e2e-8e107dc05d99\",\"metadata\":{\"league\":\"NFL\"},\"artifacts\":[ ... ],\"message\":{ ... }}"
      }
    ],
    "structuredContent": {
      "id": "019edde9-aeb4-7078-9e2e-8e107dc05d99",
      "metadata": {
        "league": "NFL"
      },
      "artifacts": [
        {
          "type": "table",
          "name": "Passing Yards Leaders",
          "content": {
            "title": "Passing Yards Leaders",
            "data": [
              {
                "rk": 1,
                "player": "Matthew Stafford",
                "team": "Los Angeles Rams",
                "pass_yards": "4707"
              },
              {
                "rk": 2,
                "player": "Jared Goff",
                "team": "Detroit Lions",
                "pass_yards": "4564"
              },
              {
                "rk": 3,
                "player": "Dak Prescott",
                "team": "Dallas Cowboys",
                "pass_yards": "4552"
              }
            ],
            "metadata": {
              "columns": [
                {
                  "title": "Player",
                  "key": "player",
                  "description": "Player Name",
                  "cutoff_year": 1920
                },
                {
                  "title": "Team",
                  "key": "team",
                  "description": "Team Name",
                  "cutoff_year": 1920
                },
                {
                  "title": "Pass Yds",
                  "key": "pass_yards",
                  "description": "Passing Yards",
                  "sort_direction": "DESC",
                  "cutoff_year": 1932
                },
                {
                  "title": "RK",
                  "key": "rk",
                  "description": "Rank",
                  "cutoff_year": 1932
                }
              ],
              "filter_column_cutoffs": [
                {
                  "column_name": "core_season_type",
                  "label": "REG",
                  "display_name": "Season Type",
                  "cutoff_year": 1920
                },
                {
                  "column_name": "core_season",
                  "label": "2025",
                  "display_name": "Season",
                  "cutoff_year": 1920
                }
              ]
            }
          }
        }
      ],
      "message": {
        "role": "assistant",
        "content": "**Matthew Stafford** led the NFL in passing yards in the 2025 regular season with **4,707 yards** for the Los Angeles Rams. Jared Goff (4,564) and Dak Prescott (4,552) were close behind in 2nd and 3rd."
      }
    }
  },
  "jsonrpc": "2.0",
  "id": 3
}

The answer is returned in result.content[0].text as a plain-text string.

Step 4: Terminate the Session

When your application is finished, close the session to free server-side resources.

curl -X DELETE "https://api.sportradar.com/ai-researcher/{league}/mcp" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "mcp-session-id: YOUR_SESSION_ID"

A successful termination returns HTTP 200.

Configuring an MCP Client (IDE Integration)

If you are using an MCP-compatible client such as VS Code or Cursor, you can point it directly at the AI Researcher MCP server without writing any code.

VS Code

"researcher-be": {
  "url": "https://api.sportradar.com/ai-researcher/{league}/mcp",
  "type": "http",
  "headers": {
    "MCP-Protocol-Version": "2025-06-18",
    "x-api-key": "YOUR_API_KEY"
  }
}

Cursor

"researcher-be": {
  "url": "https://api.sportradar.com/ai-researcher/{league}/mcp",
  "type": "http",
  "headers": {
    "x-api-key": "YOUR_API_KEY"
  }
}

Troubleshooting

Problem	Likely Cause	Resolution
`401 Unauthorized`	API key is missing or invalid	Verify your Marketplace API key is passed in the `x-api-key` header
`400 Bad Request` on POST	Missing `mcp-protocol-version` header	Include `mcp-protocol-version: 2025-06-18` on all non-initialize requests
`404` on session requests	`mcp-session-id` is missing or invalid	Re-initialize to obtain a fresh session ID
`429 Too Many Requests`	Per-minute request limit exceeded	Back off and retry after the duration in the `Retry-After` response header

🙋
More Questions?
See our AI Researcher FAQ or request access here!