I built this project because football fixture data is easy to query, but not always easy to expose cleanly to AI clients. My goal was to create a read-only Model Context Protocol server that can answer grounded football research questions using documented data from Sportmicro, without turning the integration into a sprawling API wrapper.
The shape of the project is deliberately small. Instead of mirroring every upstream endpoint, I focused on a narrow research layer for fixture lookups, match details, incidents, and lineups. That gave me a practical MCP server that stays readable, testable, and honest about what it can do.
I published the code as a public repo here: View the repository
The problem I wanted to solve
When an AI client asks about football fixtures, the answer needs more than a raw HTTP request. It needs validation, a stable interface, and enough structure that the client can trust the result.
That is the problem this repository targets. The server is meant to sit between an MCP client and the Sportmicro football API, and its job is to keep the surface area intentionally small. In practice, that means I’m not trying to expose the whole provider. I’m only exposing the parts that support fixture research:
- date-based match search
- date plus league search
- match lookup by ID
- match incidents
- match lineups
This read-only constraint is central to the design. The server should help answer research questions, not mutate upstream data. That makes the contract simpler for both the server and the client that consumes it.
How I split the architecture
The repository is divided into three main pieces:
-
src/server.tsdefines the MCP tools and validates tool input -
src/sportmicro-client.tshandles HTTP requests to Sportmicro -
src/test/server.test.tschecks validation and error handling without a live API call
That separation is the most important architectural choice in the project. The MCP layer does not know how to build URLs or attach credentials. The client layer does not know anything about protocol registration. And the tests target behavior at the seam between them.
Here’s the small but important flow I used:
- An MCP client calls one of the registered tools.
- The server validates the incoming arguments with
zod. - The Sportmicro client makes the request with the API key as a Bearer token.
- The server returns structured JSON text, or a tool error if something fails.
That flow keeps the integration honest. If the input is malformed, the request never reaches Sportmicro. If the provider fails, the server surfaces the failure in a way the client can interpret.
The implementation is also intentionally read-only. It only exposes documented football endpoints, and it doesn’t invent any additional behavior. For an MCP server that’s meant to be used in research scenarios, that predictability matters more than breadth.
The tool surface stays narrow on purpose
The server registers five tools, and I think that restraint is one of the project’s strengths.
search_matches_by_datesearch_matches_by_date_and_leagueget_match_by_idget_match_incidentsget_match_lineups
That tool set maps directly onto the research workflow I had in mind. I wanted an AI client to ask focused football questions, not wander through a giant API surface that might encourage speculative or loosely grounded answers.
The tool schemas are also specific. Date input is required in YYYY-MM-DD format. League IDs and match IDs are trimmed strings with a minimum length and maximum length constraint. Pagination inputs are optional, but when present they must be positive integers represented as strings.
That strictness is not accidental. It keeps the server from sending malformed queries upstream, and it helps the client get immediate feedback when the request itself is invalid.
A nice detail in src/server.ts is that the callback wrapper centralizes validation and error formatting. The server always returns structured text with the tool name and either data or error, which makes the result easier to inspect from the MCP side.
How the Sportmicro integration works
The Sportmicro adapter lives in src/sportmicro-client.ts, and it is very straightforward.
The client targets the football base URL and sends the API key using an Authorization: Bearer ... header. It also converts non-2xx responses into a custom SportmicroClientError, which lets the server distinguish provider failures from schema problems.
Each method maps to a documented endpoint:
/matches-by-date/matches-by-date-league/matches/matches-incidents/matches-lineups
The query handling is simple but careful. Only defined values are included in the request, so the client does not send empty parameters. That matters when you want the request shape to stay predictable and close to the provider’s expectations.
A concise example from the implementation shows the style:
getMatchesByDate(date: string, limit?: string, offset?: string) { return this.request('/matches-by-date', { date: `eq.${date}`, limit, offset }); } This is the kind of adapter code I like in a protocol server: tiny, explicit, and easy to trace back to the API contract. The logic is not trying to be clever. It just applies the provider’s documented query format and returns the response.
Project structure and local workflow
The repository is compact, which makes it easier to reason about how the pieces fit together.
src/ index.ts Entry point export server.ts MCP server and tool registration sportmicro-client.ts Typed Sportmicro HTTP client test/ Node test files A few supporting files round out the setup:
-
README.mdexplains build and run steps -
.env.exampleshows theSPORTMICRO_API_KEYvariable -
package.jsondefines TypeScript build and Node test scripts -
tsconfig.jsonandpackage-lock.jsonsupport the TypeScript workflow
The supported local workflow is straightforward:
- Node.js 20 or newer
-
SPORTMICRO_API_KEYset in the environment npm installnpm run buildnpm testnode dist/index.js
That is the complete setup path documented by the repository. The server runs with stdio transport, which is exactly what I’d expect for an MCP process that is meant to be launched by a client rather than hosted as a web service.
Testing the contract without a live API
I appreciate that the tests focus on behavior the repository can verify locally.
The test file uses Node’s built-in test runner and a fake client instead of hitting the live Sportmicro API. That keeps the tests stable and avoids coupling them to network conditions or external fixture data.
Two behaviors are covered:
- invalid date input is rejected before the client is called
- upstream Sportmicro errors are turned into actionable tool errors
That second point is especially important for an MCP server. If the upstream API fails, the server should not just crash or leak a raw exception. It should return an error payload that the client can inspect and act on.
This is also why the repository’s error model is useful. SportmicroClientError carries a message and optional status code, and the server translates it into a structured error response. The result is a more reliable boundary between the AI client and the provider.
Challenges and trade-offs
I’d describe this section as a set of design constraints rather than a postmortem, because the repository naturally reflects a few trade-offs.
- Read-only by design: this keeps the server safe and focused, but it means the scope is intentionally limited.
- Small tool surface: easier to validate and trust, though it does not attempt to cover the entire Sportmicro football API.
- Structured JSON text responses: simple and portable for MCP clients, but less expressive than a custom resource model.
- Environment-based API key handling: practical for local runs, but it requires setup before the server can start.
There is also a subtle consistency constraint in the client: query strings are only populated when values are present. That keeps requests clean, but it means the schemas and the client methods need to stay aligned with the upstream API’s expectations. In a narrow integration like this, that trade-off feels appropriate.
Sensible next improvements
A few future improvements would fit naturally if I continued the project:
- add more match-detail tools where the Sportmicro documentation supports them
- include clearer freshness metadata in tool responses
- expand test coverage for more input edge cases
- document example MCP client usage once a specific client workflow is chosen
I would treat those as extensions, not assumptions. The current project is deliberately focused, and I would keep that discipline if I added more capability later.
Takeaway
The main lesson for me was that an MCP server becomes much easier to trust when it is narrow, explicit, and read-only.
By separating protocol handling from API access, validating input before making upstream requests, and limiting the tool surface to documented football research endpoints, I ended up with something that is practical for AI clients without becoming difficult to maintain. For this kind of integration, restraint is not a limitation; it is part of the design.