End-to-end MCP client experience

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.

Agentweaver's MCP server turns the whole product into tools an AI assistant can call for you. Instead of driving only the web UI, you can connect Claude Desktop, VS Code, GitHub Copilot CLI, or GitHub Copilot desktop and ask it to create projects, cast teams, manage backlog, start coordinator work, watch runs, review artifacts, and approve outcomes. This doc explains the experience first, then gives a complete tool catalog for assistant-driven use.

Related context: Overview, Connect an MCP client, Onboarding & auth, Projects, Teams, Board, Runs, Review, Workflows, Coordinator reference, MCP reference, and MCP OAuth.

Who this is for

This is for a user who wants an MCP client to operate Agentweaver on their behalf. The assistant becomes a product operator: it can discover the user's projects, inspect the workspace, configure a team, capture and promote work, ask the coordinator to plan a goal, observe execution, and bring the result back for human review.

The MCP server is the control surface. It does not replace the UI; it mirrors the same project, board, run, workflow, memory, and review state that the UI shows. A good MCP session feels like pair-operating Agentweaver with an assistant that can both talk and act.

Connecting an MCP client

Agentweaver exposes the MCP server in two modes:

• STDIO transport for local MCP clients that launch the server as a command. The command starts the Agentweaver.Mcp app with --stdio; the server forwards tool calls to the Agentweaver API configured by AGENTWEAVER_API_URL.
• HTTP MCP transport at /mcp for hosted or shared clients. The HTTP transport runs statelessly so the caller's inbound bearer token is available during each tool invocation and can be forwarded to the backend API.

For hosted use, copy the exact https://<deployment-origin>/mcp URL from Account settings → MCP clients. The client discovers OAuth and handles browser sign-in, consent, PKCE, and token refresh. Claude Desktop additionally uses the fixed public client ID agentweaver-claude from its connector's Advanced settings; the client secret stays empty. No authorization header or manually copied credential belongs in the client configuration.

Client mode	What the client points at	Authorization experience
Hosted HTTP	The exact MCP server URL ending in /mcp; Claude also uses agentweaver-claude as its OAuth Client ID	The client uses OAuth discovery and opens the Agentweaver browser sign-in and consent flow.
Local STDIO	A trusted local development command	A repository maintainer supplies AGENTWEAVER_TOKEN through the process environment for local testing only.

The HTTP server also exposes:

• GET /healthz for unauthenticated liveness checks.
• GET /.well-known/oauth-protected-resource and GET /.well-known/oauth-protected-resource/mcp so interactive MCP clients can discover the same-origin authorization server, exact resource, and mcp:invoke scope.

For the complete interactive setup flow, see Connect an MCP client.

Authentication experience

Interactive clients discover the OAuth resource metadata, run authorization code + PKCE through Agentweaver, and receive a short-lived broker access token. OpenIddict validation uses remote OIDC discovery/JWKS and requires the configured issuer, exact <issuer>/mcp audience, keyed RS256 signature, valid lifetime, subject, and mcp:invoke scope. There is no direct-Entra, raw-GitHub, or API-key compatibility path.

A missing token receives a 401 challenge with exact resource_metadata and scope parameters and no error. Invalid credentials add error="invalid_token"; an otherwise valid token without the scope adds error="insufficient_scope". Health and protected-resource discovery remain public.

What an MCP-driven session feels like

The user starts with an intent, not a form:

"Set up this repository in Agentweaver, create a team for the onboarding-auth feature, break the work into backlog tasks, run the coordinator, and bring me the review."

The assistant turns that into a sequence of concrete tool calls and narrates the results in natural language.

1. Find or create the project. It calls project_list to see whether the repository is already registered. For a GitHub origin, it selects a repository through the Repo App selection endpoints, then calls project_create with the local working directory, origin: "github", and the short-lived repository_selection_code. The API rejects direct repository URLs and identifiers. It can also apply a blueprint. The returned project ID becomes the anchor for the rest of the session.
2. Shape the team. It calls catalog_list_roles or catalog_list_scenarios when it needs role context, then team_cast with the goal. If the user wants to inspect the proposed cast, the assistant leaves confirm=false; if the instruction is clear, it can use confirm=true to create and confirm in one step. It can then call team_get and team_member_get_charter to explain who will do what.
3. Capture work. It calls backlog_capture_task for individual tasks, or backlog_decompose_spec to preview tasks from a workspace markdown spec. When the list looks right, it calls send_all_backlog_to_ready or backlog_move_to_ready so the board reflects what is ready to be claimed.
4. Start the coordinator. It calls coordinator_start with a plain-language goal. This starts a coordinator run, but the coordinator does not dispatch child work immediately. It drafts an outcome spec and stops at a confirmation gate.
5. Confirm or revise the outcome. The assistant calls run_watch or coordinator_outcome_spec_get to surface the draft. If the user asks for changes, it calls coordinator_outcome_spec_revise; when the user accepts, it calls coordinator_outcome_spec_confirm. Only then does the coordinator resume and dispatch subagents.
6. Watch execution. It calls run_watch on the coordinator run. Progress notifications stream agent messages, tool calls, tool results, run status changes, review requests, coordinator topology, subtask events, and steering events. For point-in-time views, it can call coordinator_work_plan_get, coordinator_children_get, or orchestration_topology.
7. Review the result. When the run reaches review, the assistant calls run_show_artifacts and run_get_file for changed files, summarizes the diff, and asks for an approve/decline decision. It calls run_review only when the user approves or explicitly asks it to reject.
8. Persist context. If useful, it calls decision_inbox_submit, decision_inbox_merge, memory_record, or session_update so future agents inherit what was learned.

The user sees the same objects the UI sees: a project appears in the project list, backlog cards move across board columns, coordinator child runs show up under the orchestration, and completed runs await review until approved or rejected.

Assistant operating pattern

An effective MCP client does not call tools randomly. It keeps a small mental model of Agentweaver state and moves through it deliberately:

Moment	Assistant behavior	Useful tools
Orientation	Establish the project, repository path, team, board, and recent runs before changing anything.	project_list, project_get, team_get, backlog_get_board, project_list_runs
Design	Ask Agentweaver to propose structure, then explain the proposal in user language.	team_cast, blueprint_generate, workflow_generate, backlog_decompose_spec
Commitment	Make the smallest durable state change that matches the user's intent.	project_create, team_cast, workflow_save, backlog_capture_task, send_all_backlog_to_ready
Orchestration	Start a coordinator run, wait for the outcome spec, and stop for confirmation.	coordinator_start, run_watch, coordinator_outcome_spec_get, coordinator_outcome_spec_confirm
Supervision	Watch long work, inspect topology, and steer only when the user or state calls for it.	run_watch, orchestration_topology, coordinator_children_get, coordinator_steer
Review	Show changed files and summarize impact before approval.	run_show_artifacts, run_get_file, run_review
Memory	Save decisions and learnings that should survive the session.	decision_inbox_submit, decision_inbox_merge, memory_record, session_update

The best user experience is conversational but auditable: the assistant says what it is about to do, calls the relevant tool, summarizes the returned state, and links the next action to a visible Agentweaver concept such as a project, board card, coordinator gate, child run, or review.

Safety, idempotency, and confirmations

• Coordinator runs are confirmation-gated. coordinator_start drafts an outcome spec and suspends. Subagent work waits for coordinator_outcome_spec_confirm; coordinator_outcome_spec_revise loops the draft back through the gate.
• Review is explicit. run_review approves or rejects a run that is awaiting review. The assistant should summarize artifacts before invoking it.
• Streaming is long-running. run_watch stays open while it consumes the API run stream, reports MCP progress notifications, reconnects at the API SSE layer, and returns the final run state when complete.
• Backlog bulk promotion is safe to repeat. send_all_backlog_to_ready is idempotent: it appends backlog tasks after existing Ready tasks, preserves order, and returns "No backlog tasks to promote" on an empty backlog.
• Claimed work is protected. backlog_delete_task fails with 409 if the task has already been claimed. backlog_archive_task is the board-safe way to move a task out of active projections, including linked coordinator cards for claimed tasks.
• Heartbeat pickup has bounded settings. backlog_set_settings requires max_ready_per_heartbeat between 1 and 20. Autopilot can answer child clarifying questions during unattended coordinator runs, and auto-approval only applies to allow-with-approval tools; it does not bypass the destructive-action safety floor.
• Generation tools preview before persistence. blueprint_generate returns a generated blueprint for inspection. workflow_generate returns YAML draft only; workflow_save validates and persists it. backlog_decompose_spec defaults to preview and creates tasks only with confirm=true.
• Route ids are encoded before API calls. MCP tools URI-escape path parameters such as project_id, run_id, agent_name, task ids, and workflow ids before forwarding to the API. Crafted ids containing ../ or / remain data inside one path segment instead of changing the target route.
• Errors surface as tool errors. API failures become MCP tool errors with the HTTP status and a human-readable message. Common user-actionable errors include 400 validation failures, 401 invalid bearer token, 404 missing project/run/file, and 409 state conflicts such as no pending coordinator gate or a claimed backlog task.

Scope limit: the MCP server exposes Agentweaver operations as tools; file edits and code changes happen inside Agentweaver runs or through the client itself, not by the MCP server silently editing arbitrary files.

Tool catalog

The catalog below is grouped by the 13 MCP tool domains. Each tool name is the real MCP tool name exposed by the server.

Projects

Purpose: create, find, configure, delete, and inspect Agentweaver projects and their run lists.

Tool	What it does for the user
project_list	Lists all Agentweaver projects the caller can see.
project_get	Gets one project by ID.
project_create	Creates a project from a local working directory, optionally clones a Repo App-authorized GitHub repository via origin + repository_selection_code, can apply either a predefined blueprint_id or an inline blueprint, and can carry generated workflow YAML.
project_rename	Renames an existing project.
project_delete	Deletes a project by ID with confirmation handled by the API call.
project_configure	Updates the project's default model provider and provider-specific model IDs.
project_list_runs	Lists all runs for a project.

Team

Purpose: build and manage the project roster that runs work.

Tool	What it does for the user
team_get	Shows the current team composition for a project.
team_cast	Creates a team-casting proposal, confirms an existing proposal, or creates and confirms in one step; supports free-text, scenario, analysis, and manual casting modes.
team_member_add	Adds one member with a catalog role and optional model override.
team_member_retire	Retires a member from the project team.
team_member_get_charter	Gets a member's charter document so the assistant can explain their responsibilities.

Catalog

Purpose: discover the available building blocks for team casting.

Tool	What it does for the user
catalog_list_roles	Lists available agent roles from the catalog.
catalog_list_scenarios	Lists casting scenario templates.

Blueprints

Purpose: inspect, generate, and validate reusable project blueprints before project creation.

Tool	What it does for the user
list_blueprints	Lists predefined blueprints, including team roster, workflow, review policy, and sandbox profile.
validate_blueprint	Validates a blueprint object against schema and role constraints, returning valid:true or validation errors.
blueprint_generate	Generates a blueprint from a natural-language team and goal description for inspection before project creation.

Backlog

Purpose: manage the project's Kanban-style work intake and pickup settings.

Tool	What it does for the user
backlog_capture_task	Captures a new task into the project backlog.
backlog_edit_task	Edits a task title and/or description.
backlog_delete_task	Deletes a backlog task; fails with 409 if it has already been claimed.
backlog_move_to_ready	Moves a task from Backlog to Ready, optionally at a zero-based Ready position.
backlog_move_to_backlog	Moves a task from Ready back to Backlog, optionally at a zero-based Backlog position.
backlog_reorder_task	Reorders a task within its current Backlog or Ready bucket.
backlog_get_board	Gets the full board: Backlog, Ready, Problems, Human Review, Active, and Done.
backlog_archive_task	Archives a task off the active board; claimed tasks also archive their linked coordinator run card.
backlog_get_workflow_stages	Gets the ordered canonical run-bucket definitions for Problems, Human Review, Active, and Done.
backlog_get_settings	Reads backlog pickup settings: max_ready_per_heartbeat, pickup_autopilot, and pickup_auto_approve_tools.
send_all_backlog_to_ready	Atomically promotes all Backlog tasks to Ready, preserving order and safely doing nothing when Backlog is empty.
backlog_set_settings	Sets pickup settings; max_ready_per_heartbeat must be 1-20.
backlog_decompose_spec	Reads a workspace markdown spec, uses AI to propose backlog items, previews by default, creates with confirm=true, and caps results at 50 items.

Coordinator

Purpose: run multi-agent orchestration with an explicit outcome-spec confirmation gate.

Tool	What it does for the user
coordinator_start	Starts a coordinator orchestration from a plain-language goal; drafts an outcome spec and suspends before dispatch.
coordinator_outcome_spec_get	Reads the current persisted outcome spec for a coordinator run.
coordinator_outcome_spec_confirm	Confirms the drafted outcome spec and resumes the coordinator past the gate.
coordinator_outcome_spec_revise	Sends revision guidance so the coordinator re-drafts and re-suspends at the gate.
coordinator_work_plan_get	Gets subtasks, assigned agents, selected models, statuses, child run IDs, and dependency edges; returns null before a plan exists.
coordinator_children_get	Lists dispatched child runs with subtask status, assigned agent, selected model, and child run status.
coordinator_steer	Steers active work: stop cancels active subagents, redirect or amend injects guidance at the next turn boundary, and recovery verbs reset blocked/failed/parked subtasks; omit target to broadcast.
orchestration_topology	Gets a one-shot topology snapshot combining work plan, dependency edges, and dispatched children; use run_watch for the live graph.

Runs

Purpose: observe, inspect, retry, archive, and approve or reject coordinator and child runs.

Tool	What it does for the user
run_status	Gets the current status and details for a run.
run_watch	Streams live progress until completion, then returns final run state. It reports agent messages, tool calls/results, status updates, completion, and review requests.
run_review	Approves or rejects a run that is awaiting review.
run_show_artifacts	Lists files changed by a run.
run_get_file	Gets the content or diff for a specific file changed by a run.
run_retry	Creates a fresh run from a failed run's original inputs.
run_archive	Archives a run off active project board/list projections.

Workspace

Purpose: browse the git-backed project workspace from the base branch or active run worktrees.

Tool	What it does for the user
list_project_workspace_refs	Lists browsable refs: the base branch and active run worktrees.
list_project_workspace	Lists the flat file tree at a ref, defaulting to the base branch.
get_project_workspace_file	Gets the content of a file at a ref, defaulting to the base branch.

Workflows

Purpose: discover, generate, validate, save, and refresh project workflow definitions.

Tool	What it does for the user
workflows_list	Lists discovered workflow definitions, validation status, and the effective default.
workflow_get	Gets one workflow's full definition, including nodes, edges, and trigger.
workflows_sync	Re-reads workflow definitions from disk and refreshes the registry.
workflow_generate	Generates workflow YAML from natural language as an inspectable draft; nothing is saved until workflow_save.
workflow_save	Saves workflow YAML to the workspace after validation and dry-run binding, returning the parsed workflow definition.

Memory

Purpose: preserve decisions, inbox items, agent memory, session context, and file interoperability state.

Tool	What it does for the user
decision_inbox_submit	Submits a decision or learning to the agent inbox with an idempotency slug.
decision_inbox_list	Lists inbox entries, optionally filtered by agent, type, or status.
decision_inbox_merge	Merges a pending inbox entry into team decisions.
decision_inbox_reject	Rejects a pending inbox entry while preserving the audit trail.
decision_create	Creates a team decision directly, usually from coordinator or Scribe-style flows.
squad_decide	Submits a team decision to the decision inbox from a squad agent.
decision_list	Lists team decisions for a project, optionally filtered by type or agent.
decision_update	Updates a decision's status, content, rationale, or superseding decision link.
memory_record	Adds a memory entry for an agent with type, importance, tags, and optional session ID.
memory_list	Lists memory entries for a specific agent, optionally filtered by type or importance.
memory_get	Gets one memory entry.
memory_search	Searches memory across all agents in a project, optionally by type or OR-style tags.
session_start	Starts a work session for a project with focus, active issues, summary, and optional serialized state.
session_current	Gets the current open session for a project.
session_update	Updates the current session's focus, active issues, summary, serialized state, or ends it.
memory_export	Exports project memory to .squad/ and .agentweaver/context/ files.
memory_import	Imports .squad/decisions/inbox/*.md files into the project memory database.

GitHub App capabilities

Purpose: connect purpose-bound GitHub capabilities while Microsoft Entra remains the Agentweaver product identity. Browser handoff and status output are redacted.

Tool	What it does for the user
github_repo_app_connect	Starts the current human's Repo App browser handoff and returns only an opaque transaction ID, browser URL, and expiry.
github_repo_app_authorization_status	Polls the initiating human's Repo App handoff, returning only lifecycle status.
github_repo_app_disconnect	Disconnects the current human's Repo App authorization.
project_copilot_app_connect	Starts an Owner-authorized, project-pinned Copilot App browser handoff.
project_copilot_app_authorization_status	Polls the initiating human's project-pinned Copilot handoff.
project_copilot_app_disconnect	De-privileges a project Copilot binding for an authorized human Owner or administrator.
project_github_capability_status	Gets redacted, server-derived unattended readiness for a project.

Sandbox policy

Purpose: view and change whether agent runs have shell access for a repository.

Tool	What it does for the user
sandbox_policy_get	Gets the sandbox policy for a repository path, or the resolved default when omitted.
sandbox_policy_set	Sets whether shell access is enabled for agent runs in a repository.

Diagnostics

Purpose: inspect the health of the running Agentweaver system and coordinator heartbeat.

Tool	What it does for the user
diagnostics_get	Gets a real-time snapshot: API version, uptime, project/run counts, heartbeat state, and checkpoint GC state.
heartbeat_status	Gets coordinator heartbeat status: enabled flag, interval, last tick, and service state.

How results map back to the UI

Every successful tool call writes or reads the same state that the UI renders:

• Project tools update the project list and project settings.
• Team tools update the roster, role assignments, and charters shown in team views.
• Backlog tools update board columns and card positions.
• Coordinator tools update the orchestration panel, outcome spec, work plan, child runs, and topology.
• Run tools update run status, streamed logs, review state, artifacts, and merge/decline outcomes.
• Workflow tools update the workflow registry and the definitions available to the coordinator.
• Memory tools update decisions, inbox, agent memory, session context, and exported context files.
• Diagnostics tools reflect server-side state rather than user project state.

The practical pattern is simple: let the assistant use tools for state changes, let run_watch keep the conversation live during long operations, and use the UI whenever the user wants a visual board, topology, or review surface alongside the assistant's summary.