BirdieAPI Tool

Every other skill delegates data retrieval here. This skill owns the 14 tools, the credit costs, the league switch and the response envelope.

Coverage (from birdieapi.com/data and the league pages, check them before quoting a number):

Data is loaded and checked by BirdieAPI. It is historical and next-morning, not a live feed.

Connecting

• MCP: https://mcp.birdieapi.com/mcp (Streamable HTTP). Claude Code: claude mcp add --transport http birdieapi "https://mcp.birdieapi.com/mcp?key=YOUR_API_KEY".
• REST: POST https://mcp.birdieapi.com/v1/<tool> with a JSON body and header x-api-key: YOUR_API_KEY.
• Free tier: 500 credits every month, no card. Key at https://birdieapi.com/signup. Paid plans are on https://birdieapi.com/pricing.
• Response envelope: every REST response is wrapped as {"data": {...}}. Unwrap data before reading fields.

When to Use Each Tool

The league switch

Most tools take league: golf (the default, the PGA Tour), lpga, liv, dpwt, kornferry.

• get_scorecard takes only golf or kornferry.
• get_winner_odds has no league argument. It holds the four men's majors only.
• The sg_par3, sg_par4, sg_par5 stats exist for the PGA Tour and Korn Ferry Tour only. Other tours return null.
• Ratings are measured within one tour. A 2.0 on the LPGA and a 2.0 on the PGA Tour are not on one scale.
• Player ids are shared across tours, so a player's results on two tours join on one id.

Identifiers and seasons

• tournament_id, player_id and course_id are strings. Never guess one: get it from list_tournaments, get_schedule, search_players or get_leaderboard.
• season is a calendar year (a September 2025 event is season 2025). Exceptions from the site: the 2020 U.S. Open and the November 2020 Masters are season 2021; Korn Ferry 2020 and 2021 are one combined season stored as 2020.
• Paged tools (list_tournaments, get_player_results) return next_offset. Pass it as offset for the next page.

Tool Selection Guide

Calling Patterns

Example calls in the skills are written as the tool name followed by its JSON arguments. Over MCP pass the arguments object. Over REST send it as the body:

search_players {"query": "scheffler"}
get_ratings {"limit": 5}
get_winner_odds {"tournament_id": "401580344", "limit": 5}

curl -s -X POST https://mcp.birdieapi.com/v1/search_players \
  -H "x-api-key: $BIRDIEAPI_API_KEY" -H "content-type: application/json" \
  -d '{"query": "scheffler"}'

Real response, unwrapped from {"data": ...} and trimmed:

players[0]: player_id "9478", name "Scottie Scheffler", country "USA", tournaments 167, wins 23, first_season 2014, last_season 2026

Chain the ids: search_players gives player_id, list_tournaments gives tournament_id, and the 2-credit and 5-credit tools take those.

Errors and empty results

• A missing key or a spent balance returns an error rather than data. Tell the user which, and point to https://birdieapi.com/pricing for the credit plans.
• An empty list for a season usually means the league has no data there (for example the LPGA between 2013 and 2019). Check the league page before assuming a bug.
• A null sg_par3, sg_par4 or sg_par5 means the tour is not the PGA Tour or Korn Ferry Tour.
• Do not retry a failed call in a loop. Each attempt can spend credits.

Credit Usage

Free tier: 500 credits is about 100 five-credit calls a month. Tell the user the running total on any multi-call plan.

Commands That Do NOT Exist

Anti-patterns

BYOD

If the user brings their own round scores or odds, skip the tools and spend no credits. Minimum columns: rounds need player, tournament, round, strokes, course, date; odds need player, book, american_price, timestamp. Say when a column had to be inferred.

What to Do Next