How to Use the Football-Data.org MCP in Pydantic AI

Q: How do I configure the Football-Data.org MCP server for Pydantic AI?

Install pydantic-ai-slimmcp. Create an MCPToolset with your HTTP endpoint. Pass it to your Agent's toolsets parameter. Forget the old MCPServerHTTP class; it is deprecated.

Q: Will Pydantic AI hallucinate Football-Data.org statistics?

No. The framework validates every response from tools like getmatch against your predefined schemas. If the data doesn't match the model, the agent throws a runtime error instead of making up numbers.

Q: Can Football-Data.org track team performance in Pydantic AI?

Your agent uses listteammatches to pull the schedule and results. You filter by status, venue, and date range. The resulting data is strictly typed before your application processes it.

Q: How do I find specific geographic zones for leagues?

The listareas and getarea tools provide the geographical metadata. Your agent queries these endpoints to map competitions to specific countries or continents.

Type-safe football data extraction for your Pydantic AI agents via MCP.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Football-Data.org MCP to Pydantic AI

Create your Vinkius account to connect Football-Data.org to Pydantic AI and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Football-Data.org with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Strict Validation for Pydantic AI

The `get_match` and `list_matches` tools return live football scores that hit your Pydantic models for immediate validation. If the upstream provider changes a field type from an integer to a string, your agent fails loudly. You catch the error before it corrupts your downstream database. This strictness matters when you process high-volume events. You define the exact schema for `get_competition_standings`. The MCP server fetches the data, and the framework ensures every single row matches your expectations. No silent failures. No hallucinated statistics.

Reliable Player Statistics

Your agent calls `get_player` and `list_player_matches` to build historical profiles. Because you define the response models, you know exactly what attributes exist. Missing data triggers a validation error, forcing the agent to handle the exception gracefully. The `list_competition_scorers` tool tracks top goalscorers across specific leagues. The MCP framework guarantees that the IDs, goal counts, and player names conform to your types. You build your application logic on a foundation of absolute certainty.

Accurate Tournament Structures

The `list_competitions` and `get_competition` tools map out the available leagues. You filter by season or competition ID. The agent reads the structural data and knows exactly which tournaments are active. To dig deeper, the agent uses `list_competition_teams` to pull the exact roster of clubs in a league. It combines this with `get_team` to fetch club details. Every nested object in the JSON response is verified at runtime.

Setup guide

Set up Football-Data.org MCP in Pydantic AI

Prerequisites

Python 3.10+ installed
pydantic-ai-slim[fastmcp] package
Active Vinkius subscription with a valid endpoint token

1

Install Pydantic AI with FastMCP
Run pip install "pydantic-ai-slim[fastmcp]". The FastMCP toolset replaces the deprecated MCPServerHTTP class with full protocol support.
2

Configure the FastMCPToolset
Pass a JSON-style config dict to FastMCPToolset with your Vinkius URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. Supports Streamable HTTP, SSE, and Stdio transports.
3

Create and run your agent
Pass the toolset to Agent(toolsets=[toolset]) and call agent.run(). Swap openai:gpt-4o for any supported model — Anthropic, Google, Mistral, or Groq.

agent.py

from pydantic_ai import Agent
from pydantic_ai.toolsets.fastmcp import FastMCPToolset

toolset = FastMCPToolset({
    "mcpServers": {
        "football-dataorg-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

agent = Agent(
    "openai:gpt-4o",
    toolsets=[toolset],
    system_prompt="You have access to Football-Data.org tools.",
)

result = await agent.run("List recent Football-Data.org transactions")
print(result.output)

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Football-Data.org. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Football-Data.org now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Football-Data.org MCP in Pydantic AI

Install `pydantic-ai-slim[mcp]`. Create an `MCPToolset` with your HTTP endpoint. Pass it to your Agent's `toolsets` parameter. Forget the old `MCPServerHTTP` class; it is deprecated.

No. The framework validates every response from tools like `get_match` against your predefined schemas. If the data doesn't match the model, the agent throws a runtime error instead of making up numbers.

Your agent uses `list_team_matches` to pull the schedule and results. You filter by status, venue, and date range. The resulting data is strictly typed before your application processes it.

The `list_areas` and `get_area` tools provide the geographical metadata. Your agent queries these endpoints to map competitions to specific countries or continents.

This MCP server strictly reads external public football metrics like goal counts and match statuses. It executes in an isolated environment and has absolutely no access to your local filesystem or proprietary source code.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript