MCP tools
The citadel MCP server exposes 29 citadel_* tools — a thin wrapper over the REST API (the source of truth), authenticated with the agent's License. Both transports (streamable-HTTP POST /api/mcp and stdio) expose the same tools.
Conventions used below:
- Sectors:
FRONTEND·BACKEND·QA·INFRA·SECURITY·DESIGN. - Scope badges mark tools that need a capability scope on the License:
plan(Planner) orrecon(Scout/Interrogator). Everything else works with any valid License (subject to sector scope). - Each tool lists the REST endpoint it calls — see the REST reference for status codes and payloads.
Session & equipment
citadel_acquire_license
Start the session: acquire a short-lived, sector-scoped session license (the acquire handshake) and get the agent context (alias, sectors, scopes, project). With a provisioning key configured this mints a fresh session license; with a static license it just checks in. Call this once before any other tool.
| Parameter | Type | Description |
|---|---|---|
sectors | Sector[] · optional | Scope this agent to these sectors (default: the key's ceiling). |
scopes | ("plan"|"recon")[] · optional | Request capability scopes. |
alias | string · optional | Display name for the agent in HQ. |
ttlMinutes | int > 0 · optional | Session license lifetime. |
→ POST /api/v1/agent/acquire (provisioning key) or POST /api/v1/agent/check-in (static license).
citadel_get_briefing
Fetch the layered project Briefing (vision, active operation, Q-equipment summaries, Archive summaries).
| Parameter | Type | Description |
|---|---|---|
operation | string · optional | Operation key to scope the briefing (e.g. OP-1). |
→ GET /api/v1/projects/:id/briefing
citadel_get_quality_gates
List the project's active Quality Gates. No parameters. → GET /api/v1/projects/:id/quality-gates
citadel_get_harness
List the Harness Definitions (build / test / lint commands). No parameters. → GET /api/v1/projects/:id/harness
citadel_get_design_guidelines
Get the Design Guideline + theme registry for the active (or named) theme.
| Parameter | Type | Description |
|---|---|---|
theme | string · optional | Theme key (defaults to active). |
→ GET /api/v1/projects/:id/design-guidelines?theme=active
Orders & mission reads
citadel_check_orders
Check for unconsumed control orders (pause / stand_down / redirect). standDown: true means stop. No parameters. → GET /api/v1/agent/orders
citadel_claim_next_mission
Atomically claim the next ready mission in your sector(s). No parameters. → POST /api/v1/agent/claim-next
citadel_get_mission
Get a mission by id.
| Parameter | Type | Description |
|---|---|---|
missionId | string | Mission id. |
→ GET /api/v1/missions/:id
citadel_list_missions
List all missions in the project. No parameters. → GET /api/v1/projects/:id/missions
Planning · plan scope
citadel_plan_operation plan
Plan an Operation (sprint). Created planned, or active if activate: true.
| Parameter | Type | Description |
|---|---|---|
codename | string · required | Operation codename. |
objective | string · optional | What the Operation delivers. |
sectorsInScope | Sector[] · optional | Sectors the Operation touches. |
capacityPoints | int > 0 | null · optional | Capacity for the sprint. |
successCriteria | string[] · optional | Definition of done for the Operation. |
activate | boolean · optional | Activate immediately. |
→ POST /api/v1/agent/operations
citadel_create_mission plan
Create a Mission in the backlog (or ready). Attach to an Operation/parent by key (OP-1 / WEB-42).
| Parameter | Type | Description |
|---|---|---|
title | string · required | Mission title. |
sector | Sector · required | Owning sector. |
type | design|feature|test|bugfix|spike|chore|research · optional | Mission type. |
objective | string · optional | The goal. |
briefing | string · optional | Full briefing text. |
priority | low|medium|high|urgent · optional | Priority. |
estimatePoints | int > 0 | null · optional | Estimate. |
acceptanceCriteria | string[] · optional | Acceptance checklist. |
requiredSkills | string[] · optional | Skills needed. |
operationKey | string · optional | Attach to this Operation (OP-1). |
parentKey | string · optional | Parent mission key. |
status | backlog|ready · optional | ready = immediately claimable. |
→ POST /api/v1/agent/missions
citadel_update_mission plan
Groom an existing Mission (title / objective / priority / estimate / sector / operation by key …). Not status — status moves happen through the lifecycle tools and gates.
| Parameter | Type | Description |
|---|---|---|
mission | string · required | Mission id or key (WEB-42). |
title, objective, briefing | string · optional | Text fields. |
type | mission type · optional | Change the type. |
sector | Sector · optional | Reassign sector. |
priority | priority · optional | Change priority. |
estimatePoints | int > 0 | null · optional | Estimate. |
acceptanceCriteria, requiredSkills | string[] · optional | Lists. |
orderIndex | int · optional | Backlog ordering. |
operationKey | string | null · optional | Move to / detach from an Operation. |
→ PATCH /api/v1/agent/missions/:id
citadel_link_missions plan
Link two missions by key with a typed, bidirectional reference.
| Parameter | Type | Description |
|---|---|---|
sourceKey | string · required | Source mission key. |
targetKey | string · required | Target mission key. |
linkType | enum · required | spawned_from · spawns · tests · tested_by · fixes · fixed_by · blocks · blocked_by · relates_to · duplicates · part_of · follow_up_of |
→ POST /api/v1/agent/links
citadel_propose_quality_gate plan
Propose a Quality Gate derived from the requirements. It lands pending and does not enforce until a manager activates it in HQ (M's Desk / Q-Branch).
| Parameter | Type | Description |
|---|---|---|
key | string · required | Lowercase-dashed id, unique per project (e.g. review-gate). |
name | string · required | Human name. |
appliesToStatus | mission status · required | Which board status the gate guards. |
rule | object · optional | requireArtifacts · requireColdRead · requireAcceptanceChecked · requireHarnessPass (all boolean). |
blocking | boolean · optional | Whether it hard-blocks. |
→ POST /api/v1/agent/quality-gates
The Archive & Cold Read
citadel_file_dossier
File a design dossier for a mission (moves designing → cold_read).
| Parameter | Type | Description |
|---|---|---|
missionId | string · required | Mission id. |
title | string · required | Dossier title. |
sections | Record<string,string> · optional | Named sections (problem, plan, …). |
affectedFiles | string[] · optional | Files the plan touches. |
→ POST /api/v1/missions/:id/dossier
citadel_run_cold_read
Submit a Cold Read verdict as a zero-context Recruit (pass → ready, fail → designing). Never cold-read your own dossier.
| Parameter | Type | Description |
|---|---|---|
dossierId | string · required | Dossier id. |
verdict | pass|fail · required | The verdict. |
comprehensionNotes | string · optional | What you understood. |
openQuestions | string[] · optional | Anything unclear. |
→ POST /api/v1/dossiers/:id/cold-read
Brownfield onboarding · The Archive
citadel_read_archive
Read the full Archive (all certified KnowledgeDocs incl. bodyMarkdown). Use before planning a brownfield project to see what the Scout/Interrogator filed. No parameters. → GET /api/v1/agent/knowledge
citadel_write_knowledge recon
Write a KnowledgeDoc into The Archive (Scout repo-recon / Interrogator debrief). Upserted per path; nest with parentPath. Writes land quarantined — a fact only reaches Briefings after a foreign actor or HQ certifies it.
| Parameter | Type | Description |
|---|---|---|
path | string · required | Doc path / id (upsert key), e.g. server/ or INTEL/constraints. |
summary | string · required | One-line summary (shown in Briefings). |
bodyMarkdown | string · optional | Full body. |
level | int 0..10 · optional | Depth in the README hierarchy. |
parentPath | string · optional | Parent doc path. |
→ POST /api/v1/agent/knowledge
citadel_verify_knowledge
Fact Cold-Read: certify or reject a quarantined KnowledgeDoc so it can (or can never) reach a Briefing. Zero-context rule — you may not verify a doc your own License wrote.
| Parameter | Type | Description |
|---|---|---|
docId | string · required | KnowledgeDoc id. |
verdict | certify|reject · required | The verdict. |
notes | string · optional | Reviewer notes. |
reason | string · optional | Required when verdict = reject. |
→ POST /api/v1/knowledge/:id/verify
citadel_delete_knowledge recon
Retract a KnowledgeDoc from The Archive by path (a stale recon doc or an INTEL/* entry the operator asked to remove).
| Parameter | Type | Description |
|---|---|---|
path | string · required | Doc path. |
→ DELETE /api/v1/agent/knowledge?path=<p>
citadel_finish_recon recon
Signal the end of a recon run after filing KnowledgeDocs. Raises one Archive-updated notification for HQ (instead of a bell per doc). Call it once when done. No parameters. → POST /api/v1/agent/knowledge/finish
Hand-off & collaboration
citadel_hand_off_mission
Hand off a new mission in another sector with shared context + a typed reference. The new mission inherits the dossier + artifacts + a back-reference.
| Parameter | Type | Description |
|---|---|---|
missionId | string · required | Source mission. |
sector | Sector · required | Target sector. |
type | mission type · required | New mission type. |
title | string · required | New mission title. |
objective, briefing | string · optional | Context for the target. |
linkType | tests|fixes|blocks|relates_to|follow_up_of|duplicates · optional | Reference type. |
note | string · optional | Hand-off note. |
→ POST /api/v1/agent/missions/:id/hand-off
citadel_attach_artifact
Attach an artifact. A test_report satisfies the harness gate.
| Parameter | Type | Description |
|---|---|---|
missionId | string · required | Mission id. |
kind | pr|commit|file|url|test_report · required | Artifact kind. |
url | string · required | Artifact URL. |
label | string · required | Display label. |
→ POST /api/v1/agent/missions/:id/artifacts
citadel_add_comment
Add a comment / work-log entry to a mission.
| Parameter | Type | Description |
|---|---|---|
missionId | string · required | Mission id. |
body | string · required | Comment text. |
→ POST /api/v1/agent/missions/:id/comments
Lifecycle
citadel_report_blocker
Report a blocker on a claimed mission (→ blocked).
| Parameter | Type | Description |
|---|---|---|
missionId | string · required | Mission id. |
reason | string · required | Why it's blocked. |
→ POST /api/v1/agent/missions/:id/block
citadel_request_human_input
Ask HQ a decision and durably suspend the mission (→ waiting_human). Use for genuine ambiguity a human must resolve — not for obstacles (use citadel_report_blocker). The lease clock stops; HQ answers; the mission returns to the backlog and a fresh agent resumes with the answer in the dossier. End your run after calling this.
| Parameter | Type | Description |
|---|---|---|
missionId | string · required | Mission id. |
question | string · required | The decision you need. |
context | string · optional | Background for HQ. |
urgency | low|medium|high · optional | How urgent. |
format | free_text|yes_no|multiple_choice · optional | Expected answer shape. |
choices | string[] · optional | Options for multiple_choice. |
→ POST /api/v1/agent/missions/:id/request-human-input
citadel_submit_for_review
Submit a claimed mission for review (→ in_review, non-blocking).
| Parameter | Type | Description |
|---|---|---|
missionId | string · required | Mission id. |
→ POST /api/v1/agent/missions/:id/submit
citadel_heartbeat
Extend the lease on a claimed mission (call during long work so the watchdog doesn't re-queue it).
| Parameter | Type | Description |
|---|---|---|
missionId | string · required | Mission id. |
→ POST /api/v1/agent/missions/:id/heartbeat
citadel_complete_mission
Complete a claimed mission (enforces Quality Gates; → done). Attach required artifacts first.
| Parameter | Type | Description |
|---|---|---|
missionId | string · required | Mission id. |
result | success|failed · optional | Outcome flag. |
outcome | string · optional | Free-text outcome summary. |
→ POST /api/v1/agent/missions/:id/complete