App MCP (swapps-app-mcp)¶
swapps-app-mcp is a small, read-only Model Context Protocol server that lets an MCP client (Claude Code / Claude Desktop) query the swapps-app backend — the Django + DRF operations platform also known as IDK, served at app.swapps.com.
It is a thin, authenticated wrapper around the swapps-app REST API: each MCP tool maps to a single GET request against a DRF endpoint (clients, contracts, reports, tasks, time entries, subscriptions, and a Celery task-status check), and returns the JSON response. It does not expose POST/PUT/PATCH/DELETE — there is no way to mutate data through this server. Reads are additionally role-scoped server-side: a token only ever returns the rows its user's role is allowed to see.
Read-only by design
Every tool issues a GET request only. The server has no write path. Whatever it can read is bounded by the permissions of the DRF user that owns the configured auth token.
What it is (and isn't)¶
- Its own repository / tool. It lives at
tools/swapps-app-mcp/in the platform workspace and runs as a standalone process. It is not part of the swapps-app codebase — it only talks to swapps-app's public API surface. - A different thing from the Cloudflare MCP worker. This is a local Python (FastMCP-over-stdio) server, not the TypeScript
swapps-mcp-worker. - Auth via DRF token. Requests carry an
Authorization: Token <token>header (DRFTokenAuthentication). See Setup.
How it fits together¶
(Claude Code / Desktop)"] -->|stdio / MCP| MCP["swapps-app-mcp
(FastMCP, Python)"] MCP -->|"GET /api/... (Authorization: Token)"| API["swapps-app API
(Django + DRF)"] API --> DB[("swapps-app DB")]
The MCP client launches the server as a subprocess and speaks MCP over stdio. For each tool call, the server performs one authenticated GET against SWAPPS_API_BASE_URL and serializes the JSON result back to the client.
Cloudflare WAF on app.swapps.com
app.swapps.com sits behind Cloudflare with Super Bot Fight Mode and Browser Integrity Check, which can challenge non-browser, server-to-server HTTP clients. A WAF skip rule on the swapps.com zone allows /api/ traffic through, and the server sends an identifiable User-Agent (swapps-mcp/1.0) so its requests are visible in Cloudflare logs. Details in Setup → Cloudflare WAF.
Tech stack¶
| Category | Technology |
|---|---|
| Language | Python 3 |
| MCP framework | FastMCP (mcp package, >=1.2.0) |
| Transport | stdio |
| HTTP client | httpx (>=0.27.0) |
| Target API | swapps-app (Django + Django REST Framework) |
| Auth | DRF TokenAuthentication (Authorization: Token <token>) |
| Config | Environment variables only (see Setup) |
Documentation map¶
- Tools reference — every MCP tool exposed by
server.py, its parameters, and the swapps-app endpoint it hits. - Setup — install, configure (env var names), run, register in an MCP client, and the Cloudflare WAF gotcha.