Developer documentation

FootballGPT API & MCP

Connect the five live FootballGPT coaching tools to ChatGPT, Claude, Cursor, Windsurf, Claude Code or your own MCP client.

Streamable HTTPJSON-RPC 2.05 tools100 calls/day

Start here

Your FootballGPT account needs Pro and the API Access add-on.

This is separate from your ChatGPT or Claude plan. Sign in with the same FootballGPT account you use on footballgpt.co.

Recommended

OAuth sign-in

Use this for ChatGPT and Claude. Add FootballGPT, sign in when your browser opens, then approve the connection. You do not need an API key.

When required

Bearer API key

Use this for Cursor, Windsurf, Claude Code, OpenClaw and direct HTTP requests. Create up to three keys at /app/mcp.

Endpoint

Use the same production endpoint for OAuth and API-key clients.

Swipe sideways to view the full line.

https://footballgpt.co/api/mcp/stream

ChatGPT

If FootballGPT is already listed in the app directory, select it and choose Connect. Otherwise, use ChatGPT's custom app flow:

Open Settings → Apps → Advanced settings and enable developer mode.
Return to Settings → Apps and add a custom app.
Enter the MCP endpoint shown above.
Choose OAuth, sign in to FootballGPT, then approve the connection.
Start a new chat and enable FootballGPT from the apps menu.

Claude

If FootballGPT is already listed in the Connectors Directory, select it and choose Connect. Otherwise, add the remote connector yourself:

Open Customize → Connectors.
Select + → Add custom connector.
Enter the MCP endpoint shown above and finish adding the connector.
Choose Connect, sign in to FootballGPT, then approve the connection.
Enable FootballGPT for the conversation from Claude's connectors menu.

On Team and Enterprise plans, an organisation owner must add the connector before members can connect it.

Local Claude Desktop fallback

If your Claude Desktop version does not offer remote custom connectors, paste this into claude_desktop_config.json, restart Claude Desktop, then complete FootballGPT sign-in.

Swipe sideways to view the full line.

{
  "mcpServers": {
    "footballgpt": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote\u00400.1.38",
        "https://footballgpt.co/api/mcp/stream"
      ]
    }
  }
}

The bridge runs with npx, so Node.js must be installed. Keep the config exactly as shown. Adding a static Authorization header prevents OAuth from completing.

Try these prompts

You can ask naturally. Naming FootballGPT makes the intended tool clear when several apps are enabled.

Plan a session

“Use FootballGPT to build a 60-minute session on pressing for my U12 team.”

Get coaching advice

“Ask FootballGPT how I can help a winger who keeps receiving with their back to goal.”

Create an animation

“Use FootballGPT to animate a 4v2 rondo with player movements and coaching points.”

Search the library

“Ask FootballGPT to find practices for defending overloads with an U14 team.”

API-key clients

Create a key in FootballGPT, replace YOUR_KEY_HERE, and store it securely. A new key is shown once.

Swipe sideways to view the full line.

{
  "mcpServers": {
    "footballgpt": {
      "type": "streamable-http",
      "url": "https://footballgpt.co/api/mcp/stream",
      "headers": {
        "Authorization": "Bearer YOUR_KEY_HERE"
      }
    }
  }
}

Windsurf uses serverUrl instead of url. Key rollover keeps the old key working for 24 hours so you can update clients safely.

Tools

get_my_profileRead only

Loads your coaching profile, squad, conversation memory and coaching insights. Call this first.

Parameters: None

get_coaching_adviceRead only

Answers a football coaching question using your FootballGPT context.

Parameters: message (required), mode, advisor, age_group

generate_session_planRead only

Builds a complete training session with warm-up, activities, progressions and cool-down.

Parameters: topic (required), age_group, duration, player_count, format

animate_drillCreates a saved practice

Creates an animated practice and saves it to your FootballGPT account with a share link.

Parameters: description (required), category, age_group

search_drillsRead only

Searches the FootballGPT practice database by topic, category and age group.

Parameters: query (required), category, age_group

Limits and errors

The total limit is 100 tool calls a day. animate_drill has a separate limit of 10 calls a day. Counters reset at midnight UTC.

Rate limits return HTTP 429 with a Retry-After header and a structured rate_limited error. Temporary protection failures return HTTP 503. Authentication and entitlement failures return HTTP 401 or 403.

Troubleshooting

FootballGPT asks you to subscribe

The connected FootballGPT account needs an active Pro subscription and the API Access add-on. A free trial does not include API Access.

The sign-in window keeps reopening

Remove the FootballGPT connection, add it again, and finish sign-in in the same browser. ChatGPT and Claude should not be given a static API key.

FootballGPT is connected but no tools appear

Start a new conversation and enable FootballGPT from the app or connector menu. Workspace owners may also need to allow the connection.

A request says the limit has been reached

The allowance is 100 tool calls a day, with 10 animated practices a day. Counters reset at midnight UTC.

Still stuck? Contact support and tell us which client you are using and the exact error shown.

Data and permissions

FootballGPT can read your coaching profile, squad, conversation memory and saved practice library. Creating an animated practice saves a new practice to your FootballGPT account. It does not overwrite or delete an existing practice.

Ready to connect?

Open API Access in FootballGPT for client-specific setup and key management.

Open API setup