FACEIT CS2 Coaching MCP Server

A remote MCP server (Python + FastMCP) that reads a player's public FACEIT CS2 data, diagnoses strengths and weaknesses, and produces a personalized, data-backed improvement pathway. It's designed to deploy to Render.com and be added as a remote connector in Claude on the first try.

The server is read-only — it only reads public FACEIT data. There is intentionally no auth wall on the MCP endpoint (see Enabling real OAuth later); your FACEIT API key stays server-side and is never exposed to the connected client.

---

What it exposes

Tools

Tool	What it does
search_faceit_player(query)	Resolve a nickname / profile URL / player_id / SteamID64 → identity + level + ELO. Returns a candidates list when a nickname is ambiguous.
get_player_overview(query)	Profile + lifetime stats + active bans.
get_map_performance(query)	Per-map win rate / K-D, best & worst maps (maps with <10 matches ignored).
get_recent_form(query, limit=10)	Recent matches + per-match stats, trend, streak, consistency.
benchmark_player(query)	Percentile verdicts for K/D, K/R, HS%, ADR, Win Rate vs same-level, same-region peers (e.g. "bottom-quartile ADR for level 8"). Live peer sampling, with a labelled static-baseline fallback.
get_advanced_stats(query)	Leetify advanced metrics FACEIT doesn't expose — opening-duel %, trade %, utility damage, preaim, reaction time, aim/positioning/utility ratings. Degrades cleanly if the player has no Leetify profile. Carries required attribution.
analyze_player(query)	Headline tool — full diagnostic fusing FACEIT stats + peer benchmarks + Leetify signals: strengths, weaknesses (with severity), map/form insights, overall assessment. Reports progress while it fetches.
get_improvement_plan(query, focus=None)	Weaknesses → prioritized drills/resources tied to the player's own numbers and percentiles. focus can be aim, opening, trading, utility, positioning, maps, teamplay, tilt.
set_my_profile(query) / whoami() / clear_my_profile()	Lightweight per-user identity: say "I'm <nick>" once and later tools default to you. Best-effort in-memory; every tool still accepts an explicit query.

Prompts — coach_me(query), pre_match_prep(query, map=None), post_loss_review(query), weekly_review(query).

Resource — faceit://player/{query}/analysis exposes the latest computed analysis (served from an in-memory TTL cache, recomputed on demand — stateless-safe).

query in every tool accepts a nickname, a profile URL (faceit.com/en/players/<nick>), a raw player_id (UUID), or a SteamID64. An exact-nickname miss falls back to FACEIT search; an ambiguous nickname resolves to the best match and returns the alternatives so Claude can confirm.

How the advanced features work

• Peer benchmarking (no DB). For the target's region + skill level, the server samples ~40 peers from the FACEIT rankings, fetches their lifetime stats concurrently (throttled), and computes the target's percentile per metric. The distribution is cached in-memory per (region, level) for 6h. If sampling is rate-limited or too thin, it falls back to an approximate static baseline table (in benchmarks.py) and clearly labels the output source: "baseline".
• Leetify bridge. A FACEIT player's game_player_id is their SteamID64, and Leetify's public profile endpoint (GET /v3/profile?steam64_id=) is keyed by SteamID64. So the chain is nickname → FACEIT player → Steam64 → Leetify profile. Many players aren't on Leetify; the analysis degrades cleanly to FACEIT-only and notes that connecting Leetify would deepen the report.
• Leetify attribution (required). Any output containing Leetify-derived data includes "Data Provided by Leetify" and a View on Leetify link (https://leetify.com/app/profile/{steam64}). This project is not affiliated with or sponsored by Leetify.

---

1. Get a FACEIT Server-Side API key

1. Go to the FACEIT Developer Portal / App Studio: https://developers.faceit.com/
2. Create an app and generate a Server-Side API key (not a Client-Side key).
3. Keep it secret — it lives only as a server env var (FACEIT_API_KEY), never in client-facing code.

The current CS2 game slug is cs2 (the old csgo slug is deprecated and unused here).

---

2. Run locally

python -m venv venv
# Windows: venv\Scripts\activate    macOS/Linux: source venv/bin/activate
pip install -r requirements.txt

cp .env.example .env        # then edit .env and set FACEIT_API_KEY=...
python server.py

The server starts on http://0.0.0.0:8000 and the MCP endpoint is at http://localhost:8000/mcp.

Test it:

• Health check: curl http://localhost:8000/health → {"status":"ok"}
• MCP Inspector: point it at http://localhost:8000/mcp (Streamable HTTP transport) and call analyze_player with a nickname like donk or ZywOo.

Note: PORT overrides the default 8000 locally if set. On Render it's injected automatically.

---

3. Deploy to Render

This repo ships a Render Blueprint (render.yaml):

1. Push this repo to GitHub.
2. In Render: New → Blueprint, pick the repo. Render reads render.yaml and creates a free web service named faceit-cs2-mcp.
3. In the service's Environment settings, set FACEIT_API_KEY to your Server-Side key (it's marked sync: false, so Render won't read it from the file — set it manually). Optionally set LEETIFY_API_KEY for higher Leetify rate limits (the server works without it). ENABLE_FACEIT_OAUTH and ENABLE_ELICITATION default to "false" — leave them.
4. Deploy. Render's health probe hits /health; once it's green the service is live at https://<your-service>.onrender.com.

How the deploy is wired (and why it connects on the first try):

• Streamable HTTP transport — mcp.run(transport="http", ...), not stdio/SSE.
• Binds 0.0.0.0 and reads PORT from the env var Render injects (falls back to 8000 locally). No hard-coded port, no 127.0.0.1.
• Stateless HTTP (stateless_http=True) so Render's proxy + free-tier cold starts don't break in-memory sessions and Claude's connector reconnects cleanly.
• TLS is terminated by Render. The app serves plain HTTP on $PORT; .onrender.com provides HTTPS for free. There is deliberately no cert/SSL code in Python — that's the classic mistake.
• /health is a plain GET (200 {"status":"ok"}) and is Render's healthCheckPath; the /mcp/ endpoint is not a normal GET and must not be the health target.
• Every tool catches its own errors (404/401/429/timeouts) and returns a structured message instead of throwing, so a bad lookup never 500s mid-conversation.

---

4. Add it to Claude as a connector

In Claude → Settings → Connectors → Add custom connector, use this exact URL:

https://<your-service>.onrender.com/mcp

(Replace <your-service> with your Render service name. The path is /mcp — the server also accepts /mcp/.)

Render free-tier cold start: after ~15 min idle the service sleeps and the first request can take ~50s to wake. If the first connect attempt times out, just retry — it'll be instant once warm.

---

Per-user personalization

Two layers, both infra-free:

• Now (default, no auth, no DB): set_my_profile("<nick>") remembers who you are for the conversation, so analyze_player() etc. default to you. It's stored in-memory keyed by MCP session and is best-effort — under stateless_http=True there isn't always a stable session id, so every tool also accepts an explicit query. That explicit argument is the real guarantee: nothing breaks across cold starts. FACEIT's public API + Leetify's public API already cover the full coaching surface, so this gives a personalized experience with zero auth.

• Later (real OAuth, disabled): see the next section.

Enabling real OAuth later (advanced — needs persistent storage)

A full FACEIT OAuth provider is scaffolded in auth_faceit.py using FastMCP's OAuthProxy against FACEIT's real OIDC endpoints, gated behind ENABLE_FACEIT_OAUTH (default false). When false, the server runs open and connects to Claude first-try. Do not enable it for a normal deploy. Two caveats you must understand first:

1. Claude.ai DCR issue. Claude.ai remote connectors have a reported Dynamic Client Registration (DCR) 400 failure against FastMCP's OAuthProxy. Enabling OAuth may break the connection — test in the MCP Inspector first, not directly in Claude.
2. In-memory token storage is not production-usable. The scaffold leaves client_storage=None, so OAuth client registrations and tokens live in memory and do not survive a restart / cold start. Making this production-grade requires a persistent, encrypted store (a DB/Redis implementing AsyncKeyValue), which is deliberately out of scope for this infra-free build. The injection point is marked in auth_faceit.py.

To experiment: set ENABLE_FACEIT_OAUTH=true, MCP_JWT_SECRET, FACEIT_OAUTH_CLIENT_ID, FACEIT_OAUTH_CLIENT_SECRET, and register https://<service>.onrender.com/auth/callback as the redirect URI in your FACEIT OAuth app.

Similarly, ENABLE_ELICITATION (default false) turns on protocol-level ctx.elicit prompts. It's off because that request/response round-trip is unreliable under stateless_http and can hang a tool. With it off, ambiguous nicknames resolve to the best match and return a candidates list for Claude to disambiguate in conversation.

---

Assumptions made

• FastMCP 3.x standalone package (from fastmcp import FastMCP); the MCP endpoint mounts at /mcp.
• FACEIT stat fields are treated as strings and parsed defensively (missing fields tolerated).
• Skill-level ELO bands follow FACEIT's published CS2 table; maps need ≥10 matches to count toward best/worst; a ≥3-game active loss streak flags tilt risk. Peer benchmarking samples ~40 peers and caches distributions 6h; the static baseline table is approximate. These thresholds/tables live in analysis.py and benchmarks.py and are easy to tune.
• Leetify field names/paths were confirmed against the live OpenAPI spec at build time.

---

Tests

pip install pytest
python -m pytest tests/ -v

Unit tests (no network) cover the pure analysis engine (parsing, level bands, fragging/aim/mismatch, map ranking, form/tilt, end-to-end diagnostic), the benchmarking percentile math + static baseline, and the Leetify fusion (weakness detection, attribution, graceful absence).