MCP Tools Reference

Complete reference for all CTFFactory MCP tools. Tools are available over the HTTP/SSE transport at /mcp/sse. All production tools require a valid API key; catalog tools accept anonymous or authenticated requests.

Catalog tools

These tools require no specific scope and work with read-only data.

`list_categories`

Lists all available CTF challenge categories and the families within each.

Parameters: none

Returns: array of { category: string, families: string[] }

Example response:

[
  { "category": "Web", "families": ["Injection", "XSS", "SSRF", "Auth Bypass"] },
  { "category": "Crypto", "families": ["Encoding", "Asymmetric", "Hash"] }
]

`list_themes`

Lists available narrative themes grouped by category (Space, Corporate, Military, etc.).

Parameters: none

Returns: { categories: ThemeCategory[], themes: Theme[] }

Each theme has: id, category_id, title, icon, sort_order, is_active, anchor.

`list_specs`

Lists challenge specification records. Use this to discover valid spec_id values for produce_challenge and create_ctf.

Parameters:

Parameter	Type	Required	Description
`category`	string	No	Filter by category (case-insensitive)
`family`	string	No	Filter by family (case-insensitive)
`search`	string	No	Keyword search across category, family, subtype, description

Returns: array of spec objects including id, category, family, subtype, description, difficulty, deploy_online_available.

`get_job_status`

Returns current status and progress for a generation or deployment job.

Parameters:

Parameter	Type	Required	Description
`job_id`	string	Yes	Job UUID from produce_challenge
`tenant_id`	string	No	Inferred from auth context when authenticated

Returns: { job_id, status, progress_percent, phase, phase_label, job_kind, deploy_status, deploy_url, challenge_url?, public_urls?, service_urls_raw? }

challenge_url, public_urls, and service_urls_raw are populated once a single-challenge deploy completes.

Production tools

These tools modify state and require authentication.

`produce_challenge`

Generates a single CTF challenge. Returns a job_id to track progress.

Required scope: ctf:write

Parameters:

Parameter	Type	Required	Default	Description
`spec_id`	integer	Yes	—	Spec ID from `list_specs`
`difficulty`	string	Yes	—	`easy`, `medium`, `hard`, or `insane`
`deploy_mode`	string	No	`bundle`	`bundle`: generate only, returns downloadable ZIP. `online`: generate + deploy as standalone Docker service (no CTFd); returns `challenge_url`
`theme_id`	integer	No	—	Theme ID from `list_themes`
`language`	string	No	`en`	Content language: `en` or `fr`

Returns: { job_id, deploy_mode, hint }

After deploy_mode="online", the final get_job_status / wait_for_job response includes challenge_url and service_urls_raw.

Use wait_for_job immediately after produce_challenge for synchronous automation workflows.

`wait_for_job`

Blocks until a generation job reaches a terminal state (done, failed, or cancelled) or the timeout elapses. Ideal for sequential automation.

Parameters:

Parameter	Type	Required	Default	Description
`job_id`	string	Yes	—	Job UUID from `produce_challenge`
`tenant_id`	string	No	—	Inferred from auth context
`timeout_s`	integer	No	`120`	Maximum wait in seconds (capped at 600)

Returns: same as get_job_status plus timed_out: true if timeout elapsed before terminal state.

`create_ctf`

Creates a managed CTF flow (multi-challenge competition with CTFd). Does NOT start generation immediately — call deploy_ctf next.

Required scope: ctf:write

Parameters:

Parameter	Type	Required	Default	Description
`title`	string	Yes	—	CTF competition title
`theme_id`	integer	Yes	—	Theme ID from `list_themes`
`challenge_specs`	array	Yes	—	List of `{ spec_id: int, difficulty: string }`
`description`	string	No	`""`	Optional description
`language`	string	No	`en`	Content language
`event_start`	string	No	—	ISO-8601 event start datetime
`event_end`	string	No	—	ISO-8601 event end datetime

Returns: { flow_id, title, theme, challenges_count, deploy_status, hint }

`deploy_ctf`

Triggers challenge generation and CTFd deployment for a flow created by create_ctf. Returns immediately — use get_flow_status to poll.

Required scope: ctf:deploy

Parameters:

Parameter	Type	Required	Description
`flow_id`	string	Yes	Flow ID from `create_ctf`

Returns: { flow_id, deploy_status: "deploying", hint }

`get_flow_status`

Returns detailed production and deployment progress for a managed CTF flow.

Parameters:

Parameter	Type	Required	Description
`flow_id`	string	Yes	Flow ID from `create_ctf` or `deploy_ctf`

Returns:

Field	Description
`flow_id`	Flow identifier
`deploy_status`	`not_started`, `deploying`, `done`, `failed`
`deploy_progress`	0–100
`deploy_step_label`	Human-readable current step
`deploy_url`	CTFd URL once deployed
`produce_status`	Challenge generation status
`produce_progress`	0–100
`publish_status`	CTFd publish status
`selected_specs_count`	Total challenges requested
`produced_challenges_count`	Challenges generated so far

`list_ctfs`

Lists managed CTFs for the authenticated tenant.

Required scope: ctf:read

Parameters:

Parameter	Type	Required	Description
`status`	string	No	Filter: `not_started`, `deploying`, `done`, `failed`, `deleting`

Returns: array of { id, title, status, theme, deploy_url, created_at }

`stop_ctf`

Stops a deployed CTF instance and triggers async cleanup (teardown + archive). The CTF must be in deployed or running status.

Required scope: ctf:deploy

Parameters:

Parameter	Type	Required	Description
`managed_ctf_id`	string	Yes	Managed CTF ID from `list_ctfs`

Returns: { managed_ctf_id, status: "deleting" }

Error responses

All tools return { "error": "..." } on failure (never raise exceptions to the MCP client). Check the error key before using other fields.

{ "error": "Spec 999 not found" }
{ "error": "Authentication required for produce_challenge" }
{ "error": "CTF is already deployed" }

Scopes summary

Tool	Required scope
list_categories, list_themes, list_specs	none (anonymous OK)
get_job_status, wait_for_job	none (anonymous OK)
produce_challenge, create_ctf	`ctf:write`
deploy_ctf, stop_ctf	`ctf:deploy`
list_ctfs, get_flow_status	`ctf:read`