sporfie-public-mcp

The public MCP (Model Context Protocol) server for the Sporfie API, served at https://mcp.sporfie.com/mcp (Streamable HTTP). It lets AI agents (Claude Code, Claude Desktop, claude.ai, Cursor, anything MCP-capable) work with Sporfie events, moments, places and live streams, and answer support questions from the Sporfie Help Center.

To connect an agent, see PUBLIC_DOC.md.

Install in Cursor

From the marketplace. Open Customize in Cursor, search for Sporfie, choose Install, and sign in with your Sporfie account when Cursor asks. The link to the listing goes here once the plugin is published; browse the Cursor Marketplace until then.

One click. Add to Cursor installs the MCP server alone. The same link as a deeplink, for use inside Cursor: cursor://anysphere.cursor-deeplink/mcp/install?name=sporfie&config=eyJ1cmwiOiJodHRwczovL21jcC5zcG9yZmllLmNvbS9tY3AifQ==

By hand. Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

{
  "mcpServers": {
    "sporfie": { "url": "https://mcp.sporfie.com/mcp" }
  }
}

Cursor opens your browser to sign you in the first time (OAuth, so there is no token to copy). To use a personal API token instead, add a headers entry that reads it from your environment, so the token never sits in a file:

"headers": { "Authorization": "Bearer ${env:SPORFIE_API_TOKEN}" }

The plugin also ships one agent rule, rules/sporfie-mcp.mdc, with guidance for using the tools safely: close rather than delete, confirm destructive calls, never handle tokens.

Related MCP server: mcp-thesportsdb

Design

Credential-less bearer passthrough. Every tool call forwards the caller's Authorization: Bearer <token> (a personal API token or an OAuth access token) to the Sporfie API's /public/** endpoints, which authenticate and authorize it. The server holds no secrets and is a stateless protocol adapter (stateless_http=True, so it scales horizontally). The three Help Center tools never receive the caller's credential, because published Zendesk articles are public.

Two authentication modes. With OAuth on (SPORFIE_MCP_OAUTH_ISSUER set, as at mcp.sporfie.com), every MCP request without a Bearer token gets an HTTP 401 discovery challenge before it is dispatched: that includes tools/list and the Help Center tools. With OAuth off (the default, for example a local run), nothing is challenged: listing tools and the Help Center tools work anonymously, and each API tool needs the header. A script or probe that connects anonymously must therefore target an OAuth-off instance, or present a token.

Tool arguments are untrusted. An agent can be steered by content it read elsewhere, so:

• values that end up in a URL path must be plain Sporfie keys (letters, digits, -, _), are percent-encoded, and the final URL is compared with the tool's own template before sending;

• responses are never decompressed (a compressed answer is refused), are read under a byte cap and a total deadline, and upstream admission is bounded (see Limits);

• error bodies reach the agent only as an allowlist of safe fields with internals scrubbed out; a body that cannot be shown becomes a generic message with a short reference. The log line holds the reference, the status and the size, never the body: redaction cannot be trusted to catch every credential an upstream echoes back;

• every failure is an MCP tool error (isError: true), never a successful result;

• tools carry MCP annotations (read-only, destructive, idempotent, open-world), so clients can ask the user before a destructive call. The API still authorizes every call.

Develop

uv sync
uv run pytest                                    # offline unit tests
uv run ruff check . && uv run ruff format --check .
uv run python -m sporfie_public_server.server   # serves on :8080, MCP at /mcp

Point a local client at it:

claude mcp add --transport http sporfie-local http://localhost:8080/mcp \
  --header "Authorization: Bearer <token>"

Run the container

docker buildx build -t sporfie-public-mcp --load .
docker run --rm -p 8080:8080 sporfie-public-mcp

The image runs as an unprivileged user and writes nothing at runtime. By default the server ignores X-Forwarded-For. Behind a proxy, set SPORFIE_MCP_TRUSTED_PROXY_HOPS to the number of proxies that append to it, for example 1 behind a single load balancer. Add the public hostname to SPORFIE_MCP_ALLOWED_HOSTS. config.py documents the other settings.

Limits

Every upstream call is bounded, so one slow, huge or hostile response cannot tie the server up.

Open connections are deliberately not capped in the image. uvicorn's own limit counts idle keep-alive connections and answers 503 to health checks once it is reached, which would get a busy pod taken out of rotation. Memory is bounded by the request size above and the admission limits instead. Put a connection limit in front of the server (a load balancer, a network policy), not in it.

Release

IMAGE_REPOSITORY=<registry>/<repository> ./deployImage.sh builds and pushes an arm64 image tagged {prod|dev}-<sha7>-<version>. Rolling it out is done in the deployment repository. Afterwards, run the end-to-end tests against the rolled-out server: they fail when it runs another version than this checkout.

Security

Please report vulnerabilities privately, as described in SECURITY.md.

License

Copyright 2026 Sporfie. Licensed under the Apache License, Version 2.0.