MCP Server

How it works

The server exposes 12 read-only tools and 6 JSON resources over streamable HTTP at http://localhost:5190. Start the server yourself with dotnet run --project baseball-history-mcp (or let the Aspire AppHost host it), then point your MCP client at the URL. Health endpoints are available at /healthz and /alive.

• Requires a ConnectionStrings:Lahman value at startup. Placeholder strings containing < are rejected.
• Every tool is read-only; the server never mutates data.
• Start with the get_server_diagnostics tool or the baseball-history://server/info resource to discover the surface before calling domain tools.

Connecting

First start the server so the HTTP endpoint is listening. The server reads its database connection string from the ConnectionStrings__Lahman environment variable (the .NET double-underscore convention) or from user-secrets during local development — the client does not supply it.

ConnectionStrings__Lahman="Host=your-host;Database=baseball-history;Username=user;Password=secret" \
  dotnet run --project /path/to/baseball-history-mcp

Then point your MCP client at http://localhost:5190/.

Claude Desktop / Claude Code

Add the server to your MCP configuration:

{
  "mcpServers": {
    "baseball-history": {
      "type": "http",
      "url": "http://localhost:5190/"
    }
  }
}

VS Code

Add a .vscode/mcp.json file:

{
  "servers": {
    "baseball-history": {
      "type": "http",
      "url": "http://localhost:5190/"
    }
  }
}

Example prompts

Once connected, ask your AI assistant questions like these. It will choose and call the right tool:

Tools

Players

• search_players Search players by free-text query or last-name prefix with paging.
• get_player Get read-only detail for one player, including career batting, career pitching, and team tenures.

Franchises & Teams

• list_franchises List franchise summaries with optional filters and bounded paging.
• get_franchise Get one franchise with season-by-season history.
• get_team_season Get one exact team-season by team id, league, and year so franchise-era lookups stay deterministic.

Leaderboards

Hall of Fame

• list_hall_of_fame_inductees List inducted Hall of Fame rows with optional year/category filters and bounded paging.
• get_hall_of_fame_voting_history Get bounded Hall of Fame voting history for one player. Rows are Lahman HallOfFame ballot rows, not a prose biography.

Salaries

• get_player_salary_history Get bounded salary history for one player, ordered most recent to oldest.
• get_salary_leaders List highest salary rows with optional year filter and bounded paging.

Diagnostics

• get_server_diagnostics Inspect safe runtime posture, configured limits, and connectivity without exposing secrets.

Resources

Read-only JSON documents the client can fetch to discover the server surface and usage guidance.

Calling the server from code

Use the official MCP client SDK to connect to the running server over HTTP and call tools directly. This C# example uses the ModelContextProtocol.Client package:

using ModelContextProtocol.Client;

var transport = new HttpClientTransport(new HttpClientTransportOptions
{
    Name = "baseball-history",
    Endpoint = new Uri("http://localhost:5190/")
});

await using var client = await McpClientFactory.CreateAsync(transport);

// Discover the available tools
foreach (var tool in await client.ListToolsAsync())
{
    Console.WriteLine($"{tool.Name}: {tool.Description}");
}

// Call a tool
var result = await client.CallToolAsync(
    "get_batting_leaders",
    new Dictionary<string, object?>
    {
        ["stat"] = "hr",
        ["fromYear"] = 2000,
        ["singleSeason"] = true,
        ["pageSize"] = 5
    });

Console.WriteLine(result.Content[0].Text);

The same connect → list → call flow is available from the official Python and TypeScript MCP SDKs.

Limits & data notes

• Page sizes are capped: player search 100, franchise list 50, Hall of Fame 50, batting/pitching leaderboards 100, salary leaderboard 50.
• History is bounded: Hall of Fame voting history returns up to 25 years; salary history up to 40 seasons.
• All data is from the Lahman Baseball Database; the server is read-only.
• Player IDs follow the Lahman convention (e.g. ruthba01, troutmi01); franchise IDs match Lahman codes (e.g. NYY); team-season lookups use team id, league, and year (e.g. NYA, AL, 1927).
• Salary data is available from 1985 onward. Innings pitched is stored as outs and converted to innings (outs / 3).