Footics MCP

A remote MCP server for Footics, a World Cup 2026 prediction game. A user connects their AI assistant (Claude, ChatGPT, Cursor…) to https://mcp.footics.app/mcp, signs in with their Footics account, and the assistant can read their matches, standings and predictions — and, optionally, submit them. Inference runs on the user's side; Footics only pays for hosting.

Written in Go (cmd/mcp) with the official modelcontextprotocol/go-sdk. The server is a thin authenticated client of the Footics REST API (/v1): it holds no database connection and no service-role key — every read and write is forwarded to the API with the calling user's token, so the API stays the single source of truth and the single write point.

Architecture

AI assistant (Claude / ChatGPT)  ──MCP/HTTP──►  cmd/mcp        (/mcp)
                                                 │ internal/auth      verify user JWT (JWKS or HS256)
                                                 │ internal/tools  →  internal/apiclient  (calls /v1 with the user token)
                                                 ▼
                                          Footics API (api.footics.app) ──► Postgres

• internal/auth — verifies Supabase-issued user JWTs (JWKS asymmetric in prod, HS256 for local dev), same JWKS cache + refresh cooldown as the API.
• internal/apiclient — forwards each tool call to the Footics /v1 API with the user's bearer token (no privileged credentials here).
• internal/tools — the MCP tool definitions + per-user rate limiting.

Tools

whoami · list_matches · get_match · get_my_standing · get_my_predictions · get_leaderboard · list_my_groups · get_joker_status · search · submit_prediction (gated by MCP_ENABLE_WRITES)

Configuration

Variable	Default	Effect
FOOTICS_API_URL	—	base URL of the Footics REST API
AUTH_JWKS_URL	—	JWKS URL(s) for asymmetric token verification (prod)
AUTH_JWT_SECRET	—	HS256 secret (local dev alternative to JWKS)
MCP_ENABLED	true	false → /mcp returns 503 without verifying tokens (kill switch)
MCP_REQUIRE_AUTH	true	require a valid bearer token (401 otherwise)
MCP_ENABLE_WRITES	false	allow submit_prediction
MCP_RATE_LIMIT_PER_MIN	30	tool calls per minute per user (0 = off)

See .env.example for the full list.

Development

cp .env.example .env    # point AUTH at a local/staging GoTrue, not production
go run ./cmd/mcp        # serves on $HTTP_ADDR (default :8080), /mcp

Without an Authorization: Bearer <token> header the endpoint returns 401 (unless MCP_REQUIRE_AUTH=false). Build a static binary with go build ./cmd/mcp; the container image is the multi-stage Dockerfile (distroless).

Deployment

Runs on the Footics VPS as a Dokploy service (footics-mcp), build-from-git via deploy/compose.dokploy.yml → published at mcp.footics.app. Runbook lives in the private infra repo.

Security

Auth is required and writes are off by default. See SECURITY.md for the model and how to report a vulnerability.

License

MIT © 2026 Tom Cardoen