MCP tools

The citadel MCP server exposes 33 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) or recon (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).

Declare execution order here. dependsOn is what makes work happen in the right sequence — see Ordering the work below.

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.
dependsOn	string[] · optional	Mission keys that must be settled first.
orderIndex	int ≥ 0 · optional	Position among peers with no hard dependency.

→ POST /api/v1/agent/missions

Ordering the work

claim-next hands out the next ready mission by priority → orderIndex → creation time, and it skips any mission whose blocked_by dependencies are still open. So:

• If B can only start after A: citadel_create_mission({ title: "B", dependsOn: ["WEB-41"] }). B is never handed to an agent while A is open, and becomes claimable by itself the moment A is done or cancelled — no human step.
• If two missions are genuinely independent but should still be worked in a rough order, give them different orderIndex values.
• relates_to does not order anything. It is documentation. A plan whose dependencies are expressed with relates_to will be worked in essentially creation order.

A typo'd key in dependsOn fails the whole call with 404 — the mission is not created, so it can never end up claimable without the ordering you intended.

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

citadel_propose_harness plan

Propose a Harness Definition — the build/test/lint/run commands discovered in the repo. It lands pending and is not used until a manager activates it in HQ (Q-Branch). Read citadel_get_harness first: keys are unique per project (409 if taken).

Parameter	Type	Description
key	string · required	Lowercase-dashed id, unique per project (e.g. default).
name	string · required	Human name.
commands	object · optional	build · test · lint · run — shell commands from the repo root.
env	object · optional	Non-secret env the commands need.
notes	string · optional	Caveats (e.g. what was verified, what test needs).

→ POST /api/v1/agent/harness

citadel_propose_design_guideline plan

Propose a Design Guideline for a theme — the design system agents must follow. It lands pending and is not served to agents until a manager activates it in HQ (Q-Branch). One per (project, theme) — 409 if the theme already has one.

Parameter	Type	Description
themeKey	string · required	The theme it applies to (e.g. defcon-5).
title	string · required	Human title.
bodyMarkdown	string · optional	The guideline itself — rules an agent can follow verbatim.

→ POST /api/v1/agent/design-guidelines

The Archive & Cold Read

citadel_file_dossier

File a design dossier for a mission. It attaches to the mission and leaves the status where it is — the designing → cold_read move only fires for a mission that was already designing, and claim_next only ever hands you a ready one. So finish your run normally.

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_get_dossier

Read a mission's design dossier by key — problem, technical plan, affected files, acceptance criteria, Cold Read verdict. Use it before building against a design someone else filed, rather than reconstructing it from the briefing. The dossier usually lives on another mission than yours (the design mission, or the one you were handed off from) — check your links. Returns null if that mission carries no dossier.

Parameter	Type	Description
missionKey	string · required	Mission key (e.g. WEB-42).

→ GET /api/v1/agent/dossier?missionKey=…

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

Org-wide recall (learning from sibling projects)

Every other read is scoped to your own project. These two read across all projects in your organization — so a Scout can learn how a sibling project solved something, and a Planner can design new work on top of it, instead of rediscovering it.

Both are read-only and require the plan or recon scope (Planner or Scout); a plain execution license stays project-scoped. The organization is taken from your License, so the boundary cannot be widened. Unvetted knowledge and non-active equipment never appear, and every row names its source project.

Treat what you find as prior art, not as rules: projects differ and legitimately solve things their own way. Nothing is adopted automatically — carrying a convention into your own project is a separate, deliberate act (citadel_propose_harness / citadel_propose_quality_gate).

citadel_recall_knowledge plan | recon

Search certified Archive knowledge across all projects in the organization.

Parameter	Type	Description
query	string · optional	Narrows case-insensitively by path, summary or body text.

Returns { docs: [{ projectKey, projectName, path, level, summary, bodyMarkdown }], truncated, count }. Capped at 200 docs — truncated: true means there is more. → GET /api/v1/agent/org/knowledge

citadel_recall_equipment plan | recon

List the active Harness definitions, Quality Gates and Design Guidelines across all projects in the organization — the build/test conventions, definition of done and design rules that already work somewhere. Read them before writing your own; adopting one is a separate step. No parameters.

Returns { harness, qualityGates, designGuidelines }, each entry carrying projectKey + projectName. → GET /api/v1/agent/org/equipment

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). Only for obstacles Citadel cannot see for itself. If you are waiting on another mission, link it (blocked_by) and just finish your run: claim_next never hands out a mission with an open blocker, and it returns to the queue by itself once the last blocker is settled. See Dependencies that resolve themselves.

Parameter	Type	Description
missionId	string · required	Mission id.
reason	string · required	Why it's blocked.

→ POST /api/v1/agent/missions/:id/block

citadel_resolve_blocker

Clear a blocker on a blocked mission (→ ready) and hand it back to the queue — claim it again with claim_next. The mission must be blocked and in one of your sectors. For obstacles outside Citadel that have gone away; blocked_by dependencies clear themselves.

Parameter	Type	Description
missionId	string · required	Mission id.
note	string · required	How the blocker was cleared.

→ POST /api/v1/agent/missions/:id/resolve-blocker

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

Dependencies that resolve themselves

Link one mission to another with citadel_link_missions (linkType: "blocked_by") and Citadel schedules around it — no citadel_report_blocker, no human in HQ:

• claim_next skips it. A ready mission whose blocked_by target isn't done or cancelled is never handed out, so an agent is never given work it can't do.
• It frees itself. The moment the last blocker is settled — completed, or cancelled (it isn't coming) — a mission sitting in blocked returns to ready on its own, its claim released. The Wire records a system unblocked entry.

Keep citadel_report_blocker for obstacles Citadel can't see — an API is down, a credential is missing — and citadel_resolve_blocker to clear those once they pass.