Footics MCP

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