MCP Quickstart

CTFFactory exposes an MCP (Model Context Protocol) server that lets AI agents (Claude Desktop, Claude Code, or any MCP-compatible client) generate and deploy CTF challenges programmatically — no UI required.

Prerequisites

• A CTFFactory account with at least one API key
• Scope ctf:write to produce challenges; add ctf:deploy for CTFd deployments
• Claude Desktop ≥ 0.10 or Claude Code CLI (see config below)

Step 1 — Get your API key

Navigate to Account Settings → API Keys and create a key with scopes: - ctf:read (required for all catalog tools) - ctf:write (required to generate challenges) - ctf:deploy (required to deploy CTFs)

Step 2 — Configure your MCP client

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "ctffactory": {
      "url": "https://YOUR_INSTANCE/mcp/sse?api_key=ctff_YOUR_KEY"
    }
  }
}

Replace YOUR_INSTANCE with your CTFFactory base URL and ctff_YOUR_KEY with your API key.

Claude Code CLI

claude mcp add ctffactory \
  --transport sse \
  --url "https://YOUR_INSTANCE/mcp/sse?api_key=ctff_YOUR_KEY"

Verify connection

After adding the server, ask Claude: "List the CTF challenge categories available in CTFFactory." Claude will call list_categories and return the results.

Step 3 — Produce your first challenge

Ask Claude (natural language):

"Generate a hard web challenge and deploy it as a standalone service."

Claude will: 1. Call list_specs to find a suitable web challenge spec 2. Call produce_challenge with deploy_mode="online" 3. Call wait_for_job until the challenge is deployed 4. Return the challenge_url

Or call the tools directly from a script:

# Pseudo-code — MCP tool calls via your client SDK
spec_id = list_specs(category="web")[0]["id"]
job = produce_challenge(spec_id=spec_id, difficulty="hard", deploy_mode="online")
result = wait_for_job(job_id=job["job_id"], timeout_s=300)
print(result["challenge_url"])

Step 4 — Create a full managed CTF

1. list_themes()           → pick a theme_id
2. list_specs(category="web")  → pick spec_ids
3. create_ctf(title="...", theme_id=..., challenge_specs=[...])  → flow_id
4. deploy_ctf(flow_id=...)     → starts generation + CTFd deployment
5. get_flow_status(flow_id=...)  → poll until deploy_status="done"
6. Access the CTFd URL from get_flow_status response

Authentication reference

The API key can be passed in two ways:

Scope required per tool: ctf:read for catalog tools; ctf:write for produce_challenge and create_ctf; ctf:deploy for deploy_ctf and stop_ctf.

Health check

curl https://YOUR_INSTANCE/mcp/health
# → {"status": "ok", "service": "ctffactory-mcp"}

Next steps

• MCP Tools Reference — full parameter and return value docs for all 11 tools
• REST API Reference — use the REST API directly if you don't need MCP
• API Keys — manage scopes and rotate keys