Setup¶

How to install, configure, run, and register swapps-app-mcp in an MCP client. The server is read-only; the only secret it needs is a DRF auth token.

Prerequisites¶

Python 3 with venv.
A DRF auth token for a swapps-app user (see Get a token).
The swapps-app API base URL (for example https://app.swapps.com/api for production, or http://localhost:8000/api for local).

Get a token¶

The swapps-app API uses DRF TokenAuthentication (rest_framework.authtoken). Tokens are per-user and sent as the header Authorization: Token <token>. Generate one either way:

From the swapps-app shell (recommended):

python manage.py drf_create_token <username>

Or create/copy it from the Django admin (the Tokens section).

Treat the token as a secret

The token grants the same read access as its owning user. Never commit it. Keep it in your local .env (already git-ignored) or pass it via your MCP client's env config.

Install¶

cd tools/swapps-app-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Dependencies (requirements.txt): mcp>=1.2.0 (FastMCP) and httpx>=0.27.0.

Configuration¶

All configuration is read from environment variables. Copy the example file and fill it in:

cp .env.example .env

Variable	Required	Description
`SWAPPS_API_BASE_URL`	Yes	Base URL of the swapps-app API, e.g. `https://app.swapps.com/api`. Trailing slash is trimmed automatically.
`SWAPPS_API_TOKEN`	Yes	DRF auth token, sent as `Authorization: Token <token>`. Secret.
`SWAPPS_API_USER_AGENT`	No	Overrides the outgoing `User-Agent`. Defaults to `swapps-mcp/1.0`. See Cloudflare WAF gotcha.

Missing config fails fast

If SWAPPS_API_BASE_URL or SWAPPS_API_TOKEN is unset, the server raises a clear Missing required env vars: ... error on the first tool call.

Run¶

The server speaks MCP over stdio, so it is normally launched by the MCP client rather than run by hand. You can still smoke-test it from a shell:

set -a; source .env; set +a
.venv/bin/python -c "import server; print(server.list_clients())"

This should print a JSON list of clients (or a readable HTTP ... error string if auth/URL/WAF is misconfigured).

Register in an MCP client¶

Claude Code (CLI)¶

From the repo root:

claude mcp add swapps-app \
  --env SWAPPS_API_BASE_URL=https://app.swapps.com/api \
  --env SWAPPS_API_TOKEN=YOUR_TOKEN_HERE \
  -- /Users/andres/projects/platform/tools/swapps-app-mcp/.venv/bin/python \
     /Users/andres/projects/platform/tools/swapps-app-mcp/server.py

Claude Desktop (manual config)¶

Add the block to claude_desktop_config.json:

{
  "mcpServers": {
    "swapps-app": {
      "command": "/Users/andres/projects/platform/tools/swapps-app-mcp/.venv/bin/python",
      "args": ["/Users/andres/projects/platform/tools/swapps-app-mcp/server.py"],
      "env": {
        "SWAPPS_API_BASE_URL": "https://app.swapps.com/api",
        "SWAPPS_API_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

Restart the client, then ask it to "list the swapps-app clients" — it should invoke list_clients. See the full tools reference.

Cloudflare WAF gotcha¶

app.swapps.com sits behind Cloudflare with Super Bot Fight Mode and Browser Integrity Check enabled, which challenge HTTP clients that do not look like a browser — including legitimate server-to-server calls from this MCP.

To let the API through, the swapps.com zone has a WAF skip rule on /api/ paths (it skips the http_request_firewall_managed and http_request_sbfm phases). The server therefore does not spoof a browser; instead it sends an identifiable User-Agent (swapps-mcp/1.0) so its traffic is recognizable in Cloudflare logs and analytics. Override it with SWAPPS_API_USER_AGENT if the WAF rule is ever narrowed to a specific UA.

Security caveat

The current skip rule applies to all of /api/ for any client, so the API surface is protected by the DRF token alone — not by Cloudflare's bot protection. To scope the bypass to just this MCP, the WAF expression can be narrowed to also require http.user_agent eq "swapps-mcp/1.0" (and the matching host/path). Managing that rule is a Cloudflare-side task, outside this server.

Notes¶

Read-only: the server only issues GET requests; it never exposes POST/PUT/PATCH/DELETE.
Do not commit .env (it is already git-ignored).
The exact base URL (production / staging / local) depends on your environment.