MCP server reference

See One-call run orchestration, gates, watch and retry for the shared visual model.

See AI execution context for the shared visual model.

Experimental

The Agentweaver MCP server is experimental. Tool names, parameters, and behavior may change without notice. Pin to a known revision if you depend on the current surface.

The Agentweaver MCP server exposes Agentweaver operations as structured tool calls over hosted HTTP and local stdio transports.

For a complete, always-up-to-date list of every tool name and its one-line description, see the auto-generated MCP tool index. This page documents selected parameters and workflows. The generated tool index is the complete name/description catalog; exposed tool schemas define current complete parameter contracts.

Setup

For normal hosted use, open Account settings → MCP clients in Agentweaver and copy the exact https://<deployment-origin>/mcp URL. Add it as a remote HTTP server without headers. The client discovers Agentweaver OAuth, opens a browser for sign-in and consent, and completes authorization code + PKCE. See Connect an MCP client for supported-client instructions.

Repository workspace connection

The .mcp.json at the repository root does not register a server named agentweaver, so it never shadows your personal hosted connection. Set up the hosted endpoint once per Account settings → MCP clients in your personal MCP client config (for Copilot CLI, ~/.copilot/mcp-config.json); it takes effect automatically while working in this repo, with no workspace override to collide with.

Local stdio development

Repository developers can launch a separate local stdio server explicitly:

dotnet run --project apps/Agentweaver.Mcp -- --stdio

.mcp.json registers this local server under the distinct name agentweaver_local (not agentweaver) specifically so it can coexist with your personal hosted agentweaver entry without a name collision. Set AGENTWEAVER_TOKEN in the launching environment. It must be an Agentweaver broker token for the exact <public-origin>/mcp audience with the mcp:invoke scope. Never put the token in .mcp.json, command arguments, or source control. Optionally set AGENTWEAVER_API_URL; it defaults to http://localhost:5000.

Broker tokens only

Raw Entra access tokens, GitHub tokens, API keys, and shared service credentials are not MCP credentials. Stdio mode refuses to start without a configured broker token.

Using with GitHub Copilot CLI

Working in this repo. Your personal agentweaver entry (hosted HTTP, from ~/.copilot/mcp-config.json) connects normally — the workspace .mcp.json has no same-named entry to take precedence over it. Use /mcp show agentweaver inside an interactive session to complete OAuth and confirm that the tools are live. To drive the local stdio server instead, use /mcp show agentweaver_local (or copilot mcp get agentweaver_local).

Server-name collisions

Copilot CLI resolves MCP servers by name, merging ~/.copilot/mcp-config.json (user), .mcp.json/.github/mcp.json (workspace), and --additional-mcp-config (session) in that order — a workspace entry with the same name as a user entry takes precedence while working in this repository. .mcp.json deliberately avoids the name agentweaver (using agentweaver_local for its local stdio server instead) so your personal hosted agentweaver connection is never silently shadowed. If you name a personal or session override agentweaver_local while it is also listed under your ~/.copilot/settings.json disabledMcpServers, it will be silently skipped — check ~/.copilot/logs/process-*.log for Skipping disabled MCP server: <name> if a registered server discovers zero tools.

Authentication

Hosted clients obtain and refresh the bearer token through Agentweaver's OAuth authorization code + PKCE flow. Users do not copy the token into client configuration.

The MCP server forwards every tool call to the Agentweaver API as an authenticated HTTP request using a bearer token (Authorization: Bearer <key>).

• HTTP mode. ASP.NET/OpenIddict validates the broker JWT through remote discovery/JWKS, requiring the exact issuer and audience, keyed RS256 signature, valid lifetime, subject, and mcp:invoke. Only that validated token is forwarded to the API.
• Stdio mode. The configured AGENTWEAVER_TOKEN is forwarded. The API performs the same broker validation before any PlatformOrMcp endpoint runs.
• No fallback. Raw Entra, GitHub, API-key, malformed, expired, wrong-audience, wrong-issuer, wrong-scope, and unknown-key credentials are rejected.

Both RFC 9728 endpoints are anonymous:

• /.well-known/oauth-protected-resource
• /.well-known/oauth-protected-resource/mcp

They advertise the exact <public-origin>/mcp resource, same-origin authorization server, and mcp:invoke. A missing token receives a 401 challenge with resource_metadata and scope but no OAuth error. Invalid tokens add error="invalid_token"; missing scope adds error="insufficient_scope".

Health probe

The MCP server exposes an unauthenticated liveness probe:

GET /healthz → 200 { "status": "healthy" }

/healthz and both RFC 9728 protected-resource metadata paths are explicitly public. MCP protocol paths require broker authentication.

Error handling

All tools surface failures in a structured JSON shape:

{
  "error": "Project 'demo' not found.",
  "hint": "Call project_list to see available projects."
}

The MCP transport still raises a tool error, but the message is now actionable and consistent. Common mappings include:

• 401 → Not signed in. with Sign in to Agentweaver, then retry.
• 404 project/run/file lookups → a resource-specific error plus the relevant list/read tool in hint
• 409 review-state conflicts → Call run_status to check current state.
• -32001, 408, or 504 timeouts → Call diagnostics_get to check health, then retry.

Memory API errors preserve the API's public error code, message, and hint in the tool-error content. For example, a missing entry returns { "error": "memory_not_found", "message": "Memory entry 42 was not found.", "hint": "Call memory_list to find a valid memory entry." }.

When the failure is the run's outcome rather than the tool's outcome, run_task returns a normal JSON payload with status: "failed" or status: "timed_out" instead of throwing a transport error.

Model-provider execution context

The MCP server does not expose a separate execution-context tool. For AI-backed tools, the server prepares provider context through POST /api/ai/execution-context. It does this immediately before it sends the related API command.

The preparation request contains:

Field	Required	Description
operation	yes	The supported AI operation that the tool will start or resume.
project_id	depends on the operation	The project that supplies provider resolution and authorization context.
run_id	depends on the operation	The run that supplies continuation context.

The response contains ai_required, operation, phase, execution_key, expires_at, and effective_model_provider. Prepared context uses phase: "prepared". The MCP server forwards execution_key in If-Model-Provider-Key. It does not return that key to the MCP client. This forwarding is provider-neutral: coordinator_start, run_submit, and run_task can prepare and forward a valid BYOK context for outcome drafting, and Preview analysis continues with the same accepted provider. MCP clients do not need GitHub Copilot credentials when the effective provider is an eligible BYOK configuration.

effective_model_provider contains these fields:

• state
• provider_kind
• resolution_scope
• provider_scope
• provider_type
• model_id
• provider_key
• unavailable_reason

It contains no credentials, account names, or provider-binding identities. provider_key is an opaque comparison fingerprint. Clients must not display it or use it as execution authority.

The following MCP paths prepare provider context:

MCP tool or path	AI operation
blueprint_generate	blueprint_generation
workflow_generate	workflow_generation
skill_generate	skill_generation
team_cast in AI proposal modes	casting_generation
backlog_decompose_spec	backlog_decomposition
skill_marketplace_browse when classification is necessary	marketplace_catalog_classification
coordinator_start, run_submit, and run_task	orchestration
coordinator_outcome_spec_confirm and coordinator_outcome_spec_revise	orchestration
coordinator_steer for redirect, amend, or recovery	orchestration
run_retry	orchestration or agent_turn, based on the source run
run_review when approval resumes AI work	orchestration for coordinator runs, or agent_turn for other runs

Agentweaver records an immutable provider and capability snapshot when a run starts. MCP server enablement, disablement, and configuration changes apply to future runs; they do not switch or cancel an in-flight run during assembly, revision, recovery, or replay. The platform still revalidates that the accepted provider credential remains usable immediately before each covered model call. If it is revoked or expired, the API returns 409 model_provider_changed with redacted replacement context. The model call does not start. The API response uses this shape:

{
  "error": "model_provider_changed",
  "message": "The effective model provider changed before model invocation.",
  "context": {
    "ai_required": true,
    "operation": "orchestration",
    "phase": "prepared",
    "execution_key": "opaque-short-lived-key",
    "expires_at": "2026-09-09T13:00:00Z",
    "effective_model_provider": {
      "state": "resolved",
      "provider_kind": "platform_github_copilot",
      "resolution_scope": "project",
      "provider_scope": "platform",
      "provider_type": null,
      "model_id": "provider-model-name",
      "provider_key": "opaque-comparison-fingerprint",
      "unavailable_reason": null
    }
  }
}

The MCP transport returns a structured tool error without provider keys. A retry prepares new context. Missing context returns 409 ai_execution_context_required. Expired context returns 409 ai_execution_context_expired. Unavailable provider responses identify the remediation without exposing credentials: configure an eligible BYOK provider where supported, or connect GitHub Copilot only for a Copilot-specific operation.

run_status returns the complete run projection, including redacted effective_model_provider when provenance exists. The embedded run in run_task preserves the same field. The phase meanings are Expected for prepared, Using for active, and Used for completed.

Route parameter encoding

MCP tools treat every route path parameter as data, not as part of the URL structure. Before forwarding a tool call to the Agentweaver API, tool implementations URI-escape path segments such as project_id, run_id, agent_name, backlog task ids, workflow ids, and session ids with Uri.EscapeDataString(). This means a crafted identifier containing ../, /, or other reserved path characters cannot traverse to another endpoint or alter the route being called. Query-string parameters are not part of this path hardening and continue to use normal query encoding.

---

Projects

project_list

List all Agentweaver projects.

Parameters: none

Returns: Array of project objects with id, name, repository_path, and status.

---

project_get

Get a project by ID.

Parameter	Type	Required	Description
project_id	string	yes	Project ID

Returns: Full project object.

---

project_create

Create a new project, optionally cloning a Repo App-authorized GitHub repository and applying a blueprint.

Parameter	Type	Required	Description
name	string	yes	Project name
working_directory	string	yes	Absolute path to the local working directory
origin	string	no	Project origin: blank (default) or github
repository_selection_code	string	no	Short-lived opaque code from github_repository_selection_issue; required when origin is github. Repository URLs and identifiers are not accepted.
blueprint_id	string	no	Predefined blueprint ID to apply (exclusive with blueprint)
blueprint	object	no	Inline blueprint JSON object to apply (exclusive with blueprint_id)

Returns: Created project object with assigned id.

---

GitHub repository selection for project_create

When creating a GitHub-origin project, keep the selection flow on the same authenticated MCP connection:

1. Call github_repository_selections_list. Its redacted output supplies the selectable full_name values only.
2. Call github_repository_selection_issue with one returned full_name.
3. Pass its selection_code as repository_selection_code to project_create.

The code is bound to that caller, expires in five minutes, and is consumed once. The API resolves the clone metadata from its server-side authorization; do not send repository URLs, numeric IDs, installation IDs, permissions, tokens, or provider errors.

---

project_rename

Rename a project.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
name	string	yes	New name

Returns: Updated project object.

---

project_delete

Delete a project.

Parameter	Type	Required	Description
project_id	string	yes	Project ID

Returns: Confirmation message.

---

project_configure

Update provider settings for a project.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
default_provider	string	yes	Model provider (github-copilot or byok; legacy values remain accepted)
default_model_github_copilot	string	no	Model ID for GitHub Copilot provider
default_model_microsoft_foundry	string	no	Model ID for the BYOK provider; the legacy field name remains supported.
blueprint_generation_model	string or null	no	Blueprint-generation model. Empty or null inherits the global generation default.
workflow_generation_model	string or null	no	Workflow-generation model. Empty or null inherits the global generation default.
outcome_spec_generation_model	string or null	no	Coordinator outcome-spec drafting model. Empty or null inherits the global generation default.

Returns: Confirmation message.

---

Runs

run_submit

Legacy compatibility alias that starts a coordinator run directly in direct mode. Prefer run_task for the common one-call flow, or coordinator_start for full manual control.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
task	string	yes	Task description for the agent
agent_name	string	no	Legacy field. A value returns a tool error.
base_branch	string	no	Legacy field. A value returns a tool error.
model_source	string	no	Model provider override

Returns: { run_id, status, start_mode }.

---

run_task

Run the common coordinator workflow in one call: start the run, poll until it reaches a terminal state or a gate, and return the artifacts or the next required action.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
task	string	yes	Goal or task statement for the coordinator
workflow_id	string	no	Workflow override. Must already be in the project's allowed_workflow_ids.
model_id	string	no	Coordinator model override
start_mode	string	no	direct (default) or defineOutcome
auto_approve_tools	boolean	no	Auto-approve only repository-defined safe tools for this run and its children. Defaults to false.
autopilot	boolean	no	Auto-answer coordinator and child clarifying questions. Defaults to false.
timeout_seconds	integer	no	Maximum wait before returning partial state (default 600)
poll_interval_seconds	integer	no	Poll cadence while waiting (default 2)

Returns one of these shapes:

• Success:

{
  "run_id": "abc123",
  "status": "merged",
  "artifacts": [{ "path": "README.md" }],
  "run": { "...": "run_status payload" }
}

• Outcome-spec gate:

{
  "run_id": "abc123",
  "status": "awaiting_confirmation",
  "review_prompt": "Coordinator drafted an outcome spec. Call coordinator_outcome_spec_get ...",
  "run": { "...": "run_status payload" }
}

• Human review gate:

{
  "run_id": "abc123",
  "status": "awaiting_review",
  "review_prompt": "Run is awaiting human review. Call run_review ...",
  "run": { "...": "run_status payload" }
}

• Timeout / partial state:

{
  "run_id": "abc123",
  "status": "timed_out",
  "hint": "Call run_status for a quick snapshot or run_watch if you want to follow the live stream.",
  "run": { "...": "latest run_status payload" }
}

---

run_status

Get the current status and details of a run.

Parameter	Type	Required	Description
run_id	string	yes	Run ID

Returns: Run object with status, task, agent, timing, result, diff, outcome fields, and redacted effective_model_provider when provenance exists.

Possible status values: pending, in_progress, awaiting_review, merging, merged, declined, failed, merge_failed.

---

run_watch

Watch a run live. Streams agent messages and tool call events as MCP progress notifications until the run completes, then returns the final run state.

Parameter	Type	Required	Description
run_id	string	yes	Run ID

Returns: Final run object (same as run_status).

Progress notifications are emitted for:

• agent.message / agent.message.delta — agent output text
• tool.call — tool the agent is invoking
• tool.result — tool call outcome
• review.requested — run is ready for review

---

run_review

Approve or decline a completed run.

Parameter	Type	Required	Description
run_id	string	yes	Run ID
approved	boolean	yes	true to merge, false to decline

Returns: Review outcome with status and merge_result (commit hash when merged).

---

run_show_artifacts

List files changed by a completed run.

Parameter	Type	Required	Description
run_id	string	yes	Run ID

Returns: Array of file paths changed in the run's worktree.

---

run_get_file

Get the content or diff of a specific file from a run's worktree.

Parameter	Type	Required	Description
run_id	string	yes	Run ID
path	string	yes	Relative path to the file within the repository

Returns: File content or diff.

---

Coordinator

Coordinator launch has three relevant cases:

Launch	Behavior
defineOutcome, Autopilot off	Draft/persist a spec, then wait for confirmation or revision.
defineOutcome, launch Autopilot on	Draft, then confirm unattended through the normal seam on behalf of the accountable user.
direct	Persist a confirmed prompt-backed spec and plan directly, without a model-drafted outcome or confirmation RequestPort.

Confirmation advances into selection, decomposition, dispatch, steering and collective assembly; it is not orchestration completion. Direct mode and Autopilot do not remove workflow review/merge requirements or grant arbitrary tool permissions.

coordinator_start

Start a coordinator orchestration for a project from a plain-language goal. Proxies POST /api/projects/{id}/orchestrations.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
goal	string	yes	The outcome the coordinator should draft a spec for
model_id	string	no	Model id override; falls back to the project default, then the role default
workflow_id	string	no	Workflow override
start_mode	string	no	defineOutcome (default) or direct
auto_approve_tools	boolean	no	Auto-approve only repository-defined safe tools for this run and its children. Defaults to false.
autopilot	boolean	no	Auto-answer coordinator and child clarifying questions. Defaults to false.

Returns: { runId } for the new coordinator run.

Safe-tool auto-approval covers web_fetch and start_preview. Preview skips the human wait only: port, process-liveness, run/sandbox access and publication validation remain. Grants emit tool.auto_approved; arbitrary shell, destructive, privileged, secret-bearing and unrelated network permissions are not granted. Immutable launch policy survives retry and is inherited by children.

---

coordinator_outcome_spec_get

Get the current persisted outcome spec for a coordinator run. Proxies GET /api/runs/{id}/outcome-spec.

Parameter	Type	Required	Description
run_id	string	yes	Coordinator run ID

Returns: Outcome spec object with goal, desiredOutcome, scope, assumptions, clarifyingQuestions (omitted when none), status (drafting, awaiting_confirmation, confirmed, or declined), and confirmedBy (set once confirmed).

---

coordinator_outcome_spec_confirm

Confirm the drafted outcome spec, resuming the suspended coordinator run past the confirmation gate. Proxies POST /api/runs/{id}/outcome-spec/confirm.

Parameter	Type	Required	Description
run_id	string	yes	Coordinator run ID

Returns: The current outcome spec (same shape as coordinator_outcome_spec_get), or null if not yet readable. Surfaces 409 errors run_not_active and no_pending_gate as tool errors.

---

coordinator_outcome_spec_revise

Request a revision of the drafted outcome spec. The coordinator re-drafts using the feedback and re-suspends at the gate. Proxies POST /api/runs/{id}/outcome-spec/revise.

Parameter	Type	Required	Description
run_id	string	yes	Coordinator run ID
feedback	string	yes	Revision guidance for the coordinator

Returns: The revised outcome spec (same shape as coordinator_outcome_spec_get), or null if not yet readable. Surfaces 409 errors run_not_active and no_pending_gate as tool errors.

---

coordinator_work_plan_get

Get the work plan for a coordinator run: the decomposed subtasks and the dependency edges between them. Proxies GET /api/runs/{id}/work-plan.

Parameter	Type	Required	Description
run_id	string	yes	Coordinator run ID

Returns: Work plan object with workPlanId, coordinatorRunId, outcomeSpecId, status, subtasks (each with subtaskId, title, scope, assignedAgent, selectedModelId, phase, isolation, status, childRunId), and dependencies ({ subtaskId, dependsOnSubtaskId } edges). null before a plan is drafted.

---

coordinator_children_get

List the child runs dispatched by a coordinator run, each paired with its subtask status. Proxies GET /api/runs/{id}/children.

Parameter	Type	Required	Description
run_id	string	yes	Coordinator run ID

Returns: Array of child rows, each with subtaskId, childRunId, subtaskStatus, assignedAgent, selectedModelId, childRunStatus, worktreeBranch, treeHash, and stepCount. Empty when nothing has been dispatched.

---

coordinator_steer

Steer a coordinator run's subagents. Proxies POST /api/runs/{id}/steer.

Parameter	Type	Required	Description
run_id	string	yes	Coordinator run ID
kind	string	yes	stop, redirect, or amend
instruction	string	conditional	Required for redirect and amend. Optional for stop and recovery verbs.
target_child_run_id	string	no	Target child run ID; omit to broadcast to every active child

A stop cancels active subagents immediately. A redirect or amend takes effect at the targeted subagent's next turn boundary. Recovery verbs, such as recover, reset blocked, failed, or parked subtasks and resume dispatch. Omit target_child_run_id to target every active child. Pause is not supported.

Returns: The created steering directive with directiveId, kind, targetChildRunId, status (pending), and instruction.

---

orchestration_topology

Get a one-shot topology snapshot for a coordinator run by combining the work plan and child runs. Proxies GET /api/runs/{id}/work-plan and GET /api/runs/{id}/children.

Parameter	Type	Required	Description
run_id	string	yes	Coordinator run ID

Returns: { coordinatorRunId, workPlan, children } — the current work plan (subtasks and dependency edges) alongside the dispatched child runs. For the live graph, use run_watch (see below).

---

Watching a coordinator run

There is no separate streaming tool for the coordinator. A coordinator run is an ordinary run, so point the existing run_watch tool at the coordinator run_id to observe live drafting and orchestration. The coordinator.started, coordinator.outcome_spec, and coordinator.outcome_spec.confirmed events ride the same sequence-ordered run stream, and Phase 2 adds coordinator.work_plan, coordinator.topology (a version: 1 snapshot at seq: 0 followed by deltas), subtask.*, and coordinator.steering on that same stream. The live orchestration graph is reconstructable from run_watch alone — no extra streaming tool is needed. Use coordinator_outcome_spec_get, coordinator_work_plan_get, coordinator_children_get, or orchestration_topology for an authoritative point-in-time snapshot.

---

Team

team_get

Get the current team roster for a project.

Parameter	Type	Required	Description
project_id	string	yes	Project ID

Returns: Team object with members array, each with name, role, and status.

---

team_cast

Cast a team for a project. Supports a single-call flow (create + confirm) or a two-step flow (create proposal, inspect, then confirm separately).

Parameter	Type	Required	Description
project_id	string	yes	Project ID
goal	string	conditional	Goal description for the new team (required unless confirm_proposal_id is set)
confirm_proposal_id	string	conditional	ID of an existing proposal to confirm (skips creation)
confirm	boolean	no	Automatically confirm the newly created proposal (default false)
mode	string	no	Casting mode: free_text (default), scenario, analysis, or manual
intent	string	no	Confirmation intent: new (default, replaces team) or merge (adds to existing)

Returns: Proposal object (when confirm=false) or confirmed team object (when confirm=true or confirm_proposal_id is set).

---

team_member_add

Add a new member to a project team.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
name	string	yes	Member name (cast name, lowercase)
role_id	string	yes	Role ID from the catalog
model_id	string	no	Model ID override for this member

Returns: Updated team member entry.

---

team_member_retire

Retire a team member.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
member_name	string	yes	Member name to retire

Returns: Confirmation message.

---

team_member_get_charter

Get a team member's charter document.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
member_name	string	yes	Member name

Returns: Charter text.

---

GitHub App capabilities

Microsoft Entra remains the Agentweaver product identity. These tools connect only the purpose-bound GitHub App capabilities. Browser handoffs and polling never return OAuth state, callback cookies, credentials, repositories, installations, or permissions.

github_repo_app_connect

Start the current human's Repo App authorization.

Parameters: none

Returns: { transaction_id, browser_url, expires_at }. Open browser_url in a browser and poll the returned transaction ID.

---

github_repo_app_authorization_status

Parameter	Type	Required	Description
transaction_id	string	yes	Opaque ID returned by github_repo_app_connect.

Returns: { status }, where status is pending, completed, failed, or expired.

---

github_repo_app_disconnect

Disconnect the current human's Repo App authorization and invalidate its outstanding authorization transactions.

Parameters: none

Returns: { status: "disconnected" }.

---

project_copilot_app_connect

Start an Owner-authorized, project-pinned Copilot App connection.

Parameter	Type	Required	Description
project_id	string	yes	Project to bind. The backend derives current Owner authority.

Returns: { transaction_id, browser_url, expires_at }.

---

project_copilot_app_authorization_status

Parameter	Type	Required	Description
project_id	string	yes	Project originally passed to project_copilot_app_connect.
transaction_id	string	yes	Opaque transaction ID.

Returns: { status }, where status is pending, completed, failed, or expired.

---

project_copilot_app_disconnect

Disconnect a project Copilot binding. The API allows this de-privileging operation only to a human Project Owner or human platform administrator.

Parameter	Type	Required	Description
project_id	string	yes	Project whose binding will be disconnected.

Returns: { status: "disconnected" }.

---

project_github_capability_status

Get the server-derived, redacted unattended capability readiness for a project.

Parameter	Type	Required	Description
project_id	string	yes	Project to inspect; requires current Project Owner authority.

Returns: { status, reason_code, message, repo_app_installation_connected }.

---

Sandbox policy

sandbox_policy_get

Get the sandbox policy for a repository.

Parameter	Type	Required	Description
repository_path	string	no	Repository path to get the policy for (resolved from project when omitted)

Returns: Current sandbox policy object with shell_enabled.

---

sandbox_policy_set

Update the sandbox policy.

Parameter	Type	Required	Description
repository_path	string	yes	Repository path
shell_enabled	boolean	yes	Whether shell access is enabled for agent runs

Returns: Confirmation message.

---

Catalog

catalog_list_roles

List all available agent roles.

Parameters: none

Returns: Array of role definitions with name, description, and default model.

---

catalog_list_scenarios

List all available casting scenario templates.

Parameters: none

Returns: Array of scenario templates with id, name, description, and team shape.

---

Memory

Memory is scoped to projects. Agents use the inbox to submit learnings; the coordinator merges them into decisions. memory_export writes the live DB state to .squad/ and .agentweaver/context/ files for Squad CLI interoperability.

decision_inbox_submit

Submit a decision or learning to the agent inbox.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
agent_name	string	yes	Agent submitting the entry
slug	string	yes	Unique slug for idempotency (e.g. prefer-async)
type	string	yes	learning | pattern | update | architectural | scope | process | technical
title	string	yes	Short title
content	string	yes	Full content
rationale	string	no	Optional rationale

Returns: Created inbox entry with id and status: "pending".

---

decision_inbox_list

List inbox entries for a project.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
agent	string	no	Filter by agent name
type	string	no	Filter by entry type
status	string	no	pending (default) | merged | rejected

Returns: Array of inbox entries.

---

decision_inbox_merge

Merge a pending inbox entry into team decisions.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
entry_id	string	yes	Inbox entry ID

Returns: Resulting decision object.

---

decision_inbox_reject

Reject a pending inbox entry.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
entry_id	string	yes	Inbox entry ID

Returns: "rejected".

---

decision_create

Create a team decision directly (coordinator path).

Parameter	Type	Required	Description
project_id	string	yes	Project ID
agent_name	string	yes	Agent recording the decision
type	string	yes	architectural | scope | process | technical
title	string	yes	Short title
content	string	yes	Full content
rationale	string	no	Optional rationale

Returns: Created decision object.

---

squad_decide

Submit a team decision to the decision inbox from a squad agent. A convenience over decision_inbox_submit for agents recording a decision they want the coordinator to review and merge.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
agent_name	string	yes	Agent submitting the decision
slug	string	yes	Unique kebab-case slug for idempotency
type	string	yes	architectural | scope | process | technical | learning | pattern | update
title	string	yes	Short title
content	string	yes	Full content
rationale	string	no	Optional rationale

Returns: Created inbox entry with id and status: "pending".

---

decision_list

List team decisions for a project.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
type	string	no	Filter by type
agent	string	no	Filter by agent name

Returns: Array of decision objects.

---

decision_update

Update a decision's status or content.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
decision_id	string	yes	Decision ID
status	string	no	active | superseded | archived
content	string	no	New content
superseded_by_id	string	no	ID of the superseding decision

Returns: Updated decision object.

---

memory_record

Add a memory entry for an agent.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
agent_name	string	yes	Agent name
type	string	yes	learning | pattern | core_context | update
content	string	yes	Content
importance	string	no	low | medium (default) | high
tags	string	no	Comma-separated tags

Returns: Created memory entry.

---

memory_list

List memory entries for a specific agent.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
agent_name	string	yes	Agent name
type	string	no	Filter by type
importance	string	no	Filter by importance

Returns: Array of memory entries.

---

memory_get

Get a single memory entry.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
agent_name	string	yes	Agent name
memory_id	string	yes	Memory entry ID

Returns: Memory entry object.

---

memory_search

Cross-agent memory search across the whole project.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
type	string	no	Filter by type
tags	string	no	Comma-separated tags (OR semantics)

Returns: Array of memory entries from all agents.

---

session_start

Start a new work session. Auto-ends any existing open session.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
session_id	string	yes	Unique session ID
focus_area	string	yes	Current focus description
active_issues	string	no	Active issues being worked

Returns: Created session object.

---

session_current

Get the current open session for a project.

Parameter	Type	Required	Description
project_id	string	yes	Project ID

Returns: Current session object or null.

---

session_update

Update focus, summary, or end the current session.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
focus_area	string	no	New focus area
active_issues	string	no	Active issues
summary	string	no	Text to append to the session summary
end	boolean	no	true to close the session

Returns: "updated".

---

memory_export

Export project memory to .squad/ and .agentweaver/context/ files for Squad CLI interoperability.

Parameter	Type	Required	Description
project_id	string	yes	Project ID

Returns: An export report with exported, item counts, and files, the repository-relative paths written by the operation. The report always includes the generated .agentweaver/context/boundaries.md and .agentweaver/context/patterns.md ledgers.

---

memory_import

Import .squad/decisions/inbox/*.md files from disk into the project memory database.

Parameter	Type	Required	Description
project_id	string	yes	Project ID

Returns: "imported".

---

Runs (continued)

run_retry

Retry a failed run by creating a fresh run from its original inputs.

Parameter	Type	Required	Description
run_id	string	yes	Run ID to retry

Returns: "Retried run {run_id} -> new run {new_run_id}." — confirmation with the new run ID.

---

run_archive

Archive a run off the active project board.

Parameter	Type	Required	Description
run_id	string	yes	Run ID

Returns: Updated run object.

---

project_list_runs

List all runs for a project.

Parameter	Type	Required	Description
project_id	string	yes	Project ID

Returns: Array of run objects with run_id, status, task, agent_name, and timing fields.

---

Backlog

The backlog is the project's Kanban board for task management. Task state is Backlog, Ready or Claimed. A claimed card projects its run into Problems, Human Review, Active or Done. Archiving hides eligible items; it is not another task-state enum value.

backlog_capture_task

Capture a new task into the project backlog.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
title	string	yes	Task title
description	string	no	Task description

Returns: Created task object with id, title, description, and status: "backlog".

---

backlog_edit_task

Edit the title and/or description of a backlog task.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
task_id	string	yes	Task ID
title	string	yes	New title
description	string	no	New description (omit to clear)

Returns: Updated task object.

---

backlog_delete_task

Delete a backlog task. Fails with 409 if the task has already been claimed.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
task_id	string	yes	Task ID

Returns: "Task deleted successfully.".

---

backlog_move_to_ready

Move a task from Backlog to Ready, optionally at a specific position.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
task_id	string	yes	Task ID
target_index	integer	no	Zero-based target position in Ready column (appends to end when omitted)

Returns: Updated task object with status: "ready".

---

backlog_move_to_backlog

Move a task from Ready back to Backlog, optionally at a specific position.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
task_id	string	yes	Task ID
target_index	integer	no	Zero-based target position in Backlog column (appends to end when omitted)

Returns: Updated task object with status: "backlog".

---

backlog_reorder_task

Reorder a task within its current bucket (Backlog or Ready) to a new zero-based position.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
task_id	string	yes	Task ID
target_index	integer	yes	Zero-based target position within the task's current bucket

Returns: Updated task object.

---

backlog_get_board

Get the full Kanban board for a project.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
include_terminal_history	boolean	no	Include terminal/done history (default false)

Returns: Board object with columns: backlog, ready, problems, human_review, active, and done. Each column is an array of task cards with id, title, description, status, and linked run details.

---

backlog_archive_task

Archive a backlog task off the active board.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
task_id	string	yes	Task ID

Returns: Updated task object with status: "archived".

---

backlog_get_workflow_stages

Get the ordered canonical run-bucket definitions for a project (Problems, Human Review, Active, Done).

Parameter	Type	Required	Description
project_id	string	yes	Project ID

Returns: Array of workflow stage definitions, each with name, label, and terminal flag.

---

backlog_get_settings

Get the per-project backlog pickup settings.

Parameter	Type	Required	Description
project_id	string	yes	Project ID

Returns: Settings object with max_ready_per_heartbeat, pickup_autopilot, and pickup_auto_approve_tools.

---

backlog_set_settings

Set the per-project backlog pickup settings.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
max_ready_per_heartbeat	integer	yes	Maximum Ready tasks claimed per heartbeat tick (1–20)
pickup_autopilot	boolean	yes	Auto-answer clarifying questions during unattended coordinator runs
pickup_auto_approve_tools	boolean	yes	Auto-approve repository-defined safe tools during unattended runs; other approval boundaries remain enforced

Returns: Updated settings object.

---

send_all_backlog_to_ready

Bulk-promote all Backlog tasks to Ready in one atomic operation.

Parameter	Type	Required	Description
project_id	string	yes	Project ID

Returns: "Promoted N backlog task(s) to Ready." or "No backlog tasks to promote.".

---

backlog_decompose_spec

Read a markdown spec file from the project's workspace, run AI decomposition, and return proposed backlog items. Use confirm=true to create the tasks; confirm=false (default) previews only. Results are capped at 50 items.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
file_path	string	yes	Relative path to a markdown file within the project workspace
confirm	boolean	no	true creates the tasks; false (default) returns a preview only

Returns: { proposed_items: [{ title, description, already_exists }], was_capped, total_found }. already_exists flags items already present in the backlog (dedup by title + source file).

---

Blueprints

Blueprints are pre-packaged project configurations specifying a team roster, workflow, review policy, and sandbox profile.

list_blueprints

List the predefined Agentweaver blueprints.

Parameters: none

Returns: Array of blueprint objects, each with id, name, description, roster, workflow, review_policy, and sandbox_profile.

---

blueprint_generate

Generate a new blueprint from a natural language description of the team and goals.

Parameter	Type	Required	Description
description	string	yes	Plain-language description of the team and workflow

Returns: Generated blueprint object. Returns 422 if the model output cannot be validated.

---

validate_blueprint

Validate a blueprint object against the schema and role constraints.

Parameter	Type	Required	Description
blueprint	object	yes	Blueprint JSON object with id, name, description, roster, workflow, review_policy, sandbox_profile

Returns: { "valid": true, "errors": [] } on success, or { "valid": false, "errors": [...] } with a list of validation errors.

---

Diagnostics

diagnostics_get

Get a real-time system diagnostics snapshot.

Parameters: none

Returns: Object with api_version, uptime, project_count, active_run_count, heartbeat_state, and checkpoint_gc_state.

---

heartbeat_status

Get the current coordinator heartbeat service status.

Parameters: none

Returns: Object with enabled, interval_seconds, last_tick_at, and service_state (running | waiting_first_tick | disabled).

---

Workflows

MCP exposes workflow triggers today in two ways:

• workflows_list and workflow_get surface the current trigger on each workflow, including event predicates when one is configured.
• workflow_generate can draft schedule or event triggers from natural-language descriptions, and workflow_save can persist trigger edits by saving the workflow YAML.

There is no dedicated MCP tool yet for the structured REST trigger CRUD surface (GET/PUT/DELETE /api/projects/{projectId}/workflows/{workflowId}/trigger). In MCP, trigger writes currently go through full-workflow YAML edits rather than a workflow_set_trigger / workflow_configure helper.

workflows_list

List all discovered workflow definitions for a project.

Parameter	Type	Required	Description
project_id	string	yes	Project ID

Returns: Array of workflow summaries with id, name, validation state, effective-default status, and trigger (when configured).

---

workflow_get

Get the full definition of a single workflow by ID.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
workflow_id	string	yes	Workflow ID

Returns: Full workflow definition with id, name, trigger, nodes, and edges. For event triggers, the returned predicate objects use the same structured shape as the REST API (hasLabel, baseBranch, commentMatches, or, not, and so on).

---

workflows_sync

Re-read the project's workflow definitions from disk, refreshing the in-memory registry.

Parameter	Type	Required	Description
project_id	string	yes	Project ID

Returns: Updated workflow list (same shape as workflows_list).

---

workflow_generate

Generate a new workflow YAML draft from a natural-language description. Nothing is written to disk — use workflow_save to persist (FR-065). Natural-language trigger inference covers both schedule prompts (“every Monday at 09:00 UTC”) and curated GitHub event prompts (“when someone comments /agentweaver:triage”).

Parameter	Type	Required	Description
project_id	string	yes	Project ID
description	string	yes	Plain-language description of the pipeline

Returns: { yaml, workflow_id, was_corrected } — the draft YAML, a suggested id (matching the id field), and whether a correction pass was applied.

---

workflow_save

Persist a workflow YAML to the project workspace (.agentweaver/workflows/). Validates and dry-run binds every node before writing; on success the workflow is immediately coordinator-selectable. This is also the current MCP write path for trigger changes.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
workflow_id	string	yes	Workflow ID (must match the id in the YAML)
yaml	string	yes	Workflow YAML to save

Returns: The full WorkflowDefinitionDto (id, nodes, edges, trigger, validation status). Returns 400 on YAML parse errors, malformed trigger predicates, an unwired node type, or an id/route mismatch.

---

Workspace

Browse the git-backed project workspace. Supports reading files at any branch or run worktree ref.

list_project_workspace_refs

List the browsable git refs for a project workspace: the base branch and any active run worktrees.

Parameter	Type	Required	Description
project_id	string	yes	Project ID

Returns: Object with base_branch (string) and worktrees (array of { branch, run_id }).

---

list_project_workspace

List the flat file tree for a project workspace at a given ref.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
ref	string	no	Branch name or worktree branch to browse (defaults to base branch)

Returns: Array of workspace node objects, each with path, type (blob or tree), and size.

---

get_project_workspace_file

Get the content of a file in a project workspace at a given ref.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
path	string	yes	Relative file path within the workspace (forward slashes, e.g. src/main.cs)
ref	string	no	Branch name or worktree branch (defaults to base branch)

Returns: Object with path, content (base64-encoded), encoding, and size.

Cross-surface launch and provider contracts

Coordinator launch has three relevant cases:

Launch	Behavior
defineOutcome, Autopilot off	Draft/persist a spec, then wait for confirmation or revision.
defineOutcome, launch Autopilot on	Draft, then confirm unattended through the normal seam on behalf of the accountable user.
direct	Persist a confirmed prompt-backed spec and plan directly, without a model-drafted outcome or confirmation RequestPort.

Confirmation advances into selection, decomposition, dispatch, steering and collective assembly; it is not orchestration completion. Direct mode and Autopilot do not remove workflow review/merge requirements or grant arbitrary tool permissions.

run_task defaults to Direct; coordinator_start defaults to defineOutcome; run_submit is a legacy Direct Coordinator alias, not the removed standalone REST route. Autopilot auto-answers questions and, when set at launch in defineOutcome, confirms the draft unattended; it does not grant tool permissions. Heartbeat pickup defaults are separate from false-by-default explicit launches.

MCP prepares AI context internally, rejects unresolved providers, and forwards its execution_key as If-Model-Provider-Key. The forwarding key is not a public tool parameter. Workflow responses include ordered triggers plus first-trigger alias trigger; writes still use complete workflow YAML generation/save rather than a dedicated structured trigger-edit tool.

Diagram details and constraints

Element	Contract
title	One goal, one collective review
subtitle	Confirm intent, dispatch bounded work, then integrate and review the whole result.
group-title0	Plan and execute
group-title1	Integrate, review, finish
Confirm intent	Confirm intent
Confirm intent	Draft the OutcomeSpec
Confirm intent	human confirmation
Plan the work	Plan the work
Plan the work	Persist a WorkPlan DAG
Plan the work	subtasks + dependencies
Dispatch children	Dispatch children
Dispatch children	Run the eligible frontier
Dispatch children	per-child worktrees
Merge + Scribe	Merge + Scribe
Merge + Scribe	Approved integration path
Merge + Scribe	MergeWorktree → Scribe
Collective review	Collective review
Collective review	One human decision
Collective review	approve / revise / decline
Integrate + gates	Integrate + gates
Integrate + gates	Assemble child branches
Integrate + gates	configured checks / review
e1	confirm
e2	dispatch
e3	settled work
e4	request review
e5	approve
assurance-title	DO NOT CONFUSE ASSEMBLY WITH PUBLICATION
assurance-line1	The collective workflow reaches MergeWorktree and Scribe; this graphic does not promise PR creation.
assurance-line2	A blocked assembly can be recovered. Review approval does not itself mark the run complete.
Confirm intent	Input
Confirm intent	Human goal
Confirm intent	Artifact
Confirm intent	OutcomeSpec
Confirm intent	Gate
Confirm intent	Confirm or revise
Confirm intent	Scope
Confirm intent	Explicit assumptions
Plan the work	Select
Plan the work	Workflow choice
Plan the work	WorkPlan DAG
Plan the work	Owners
Plan the work	Named subtasks
Plan the work	Store
Plan the work	Persist dependencies
Dispatch children	Ready
Dispatch children	Satisfied dependencies
Dispatch children	Files
Dispatch children	Child-owned worktree
Dispatch children	Observe
Dispatch children	Child status / results
Dispatch children	Failure
Dispatch children	Blocks dependents
Merge + Scribe	Merge
Merge + Scribe	Reviewed integration
Merge + Scribe	Then
Merge + Scribe	Collective Scribe
Merge + Scribe	Record
Merge + Scribe	Promote decisions
Merge + Scribe	Decline
Merge + Scribe	Skips Scribe
Collective review	Approve
Collective review	Proceed to merge
Collective review	Revise
Collective review	Steer / redispatch
Collective review	No Scribe path
Collective review	Blocked
Collective review	Recoverable state
Integrate + gates	Child branches
Integrate + gates	Target
Integrate + gates	Integration branch
Integrate + gates	Gates
Integrate + gates	Selected checks
Integrate + gates	Output
intent	Scope and assumptions are explicit; Revision reopens the intent gate
plan	Outcome-complete decomposition; Bounded work with named owners
dispatch	Observe child status and results; Failure / RAI blocks dependents
finish	Decline skips Scribe; No automatic PR claim here
review	Changes can redispatch work; Blocked is recoverable, not terminal
integrate	Collective—not per-child delivery; Merge failure may still run Scribe
notes	DO NOT CONFUSE ASSEMBLY WITH PUBLICATION; The collective workflow reaches MergeWorktree and Scribe; this graphic does not promise PR creation.; A blocked assembly can be recovered. Review approval does not itself mark the run complete.
groups	Plan and execute; Integrate, review, finish