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 exposes product operations as tools an AI assistant can call for you. Connect a compatible client to create projects, cast teams, manage backlog, start work, watch runs, and bring artifacts back for review. This page explains the journey and representative tools; use the generated tool index and live tools/list for the connected server's complete catalog.

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. Choose one intake path for the work. For queued work, call backlog_capture_task or preview a spec with backlog_decompose_spec, then promote the agreed tasks to Ready. Background pickup atomically claims and reserves a coordinator run and starts it unattended. Do not also manually start the same goal. For immediate work, skip that pickup path and use coordinator_start or run_task.
4. Choose the immediate start mode. coordinator_start defaults to defineOutcome: draft the outcome spec, then suspend for confirmation. Its direct mode skips that gate. run_task defaults to direct and waits for completion or a gate before returning the next action.
5. Confirm or revise when a gate exists. Use coordinator_outcome_spec_get to surface the draft, coordinator_outcome_spec_revise for feedback, and coordinator_outcome_spec_confirm only with the user's authorization. Direct and unattended starts do not add this manual step.
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 eligible context. Use decision_inbox_submit, memory_record, or session_update for durable records. Acceptance and promotion require an authorized owner or verified Coordinator; recording alone does not grant team-wide prompt eligibility.

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	Choose Ready pickup or immediate start; stop for confirmation in Define Outcome mode.	coordinator_start, run_task, 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

• Confirmation depends on start mode. coordinator_start defaults to Define Outcome, with confirmation before dispatch. Direct mode and unattended pickup skip that manual outcome gate; tool approvals and human review are separate boundaries.
• 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 following task-oriented tables are representative, not a versioned exhaustive catalog. The generated MCP tool index documents the source catalog; the client's tools/list is authoritative for the server it actually connected to.

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 optional outcome-spec confirmation gate.

Tool	What it does for the user
coordinator_start	Starts a coordinator orchestration; defineOutcome is the default gated mode, while direct skips the outcome-spec gate.
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_task	Starts immediate work (Direct by default), waits for completion or a gate, and returns artifacts or the next action.
run_submit	Legacy compatibility alias for Direct coordinator start; prefer run_task or coordinator_start.
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	Retries failed work; eligible coordinator recovery resumes the same run, otherwise a new linked run is created. Inspect the returned run ID.
run_archive	Archives a run off active project board/list projections.
start_preview	Requests a preview for an already-started, verified sandbox server; approval and retained runtime resources determine availability.

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	Records a decision under the server's authority and trust rules; an arbitrary caller cannot make approved policy by naming a governance agent.
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.
github_repository_selections_list	Lists repositories available through the caller's Repo App authorization.
github_repository_selection_issue	Issues a short-lived, caller-bound, single-use selection code for GitHub-backed project creation.
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.

Skills

Purpose: acquire reusable instructions into a project catalog, then assign active skills to agents.

Tool	What it does for the user
skill_list, skill_get	Inspect catalog entries and full instructions.
skill_create, skill_generate	Create a skill or generate a draft to inspect first.
skill_import_preview, skill_import	Preview trusted-source candidates, then import selected skills.
skill_marketplaces_list, skill_marketplace_browse, skill_marketplace_import	Discover approved marketplaces and import candidates with provenance.
skill_sync	Refresh supported skill folders from the connected repository.
skill_assign, skill_unassign, skill_assignments_list	Manage agent-specific instruction eligibility, separately from acquisition.

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.

Diagram details and constraints

Element	Contract
title	Assistant-driven work
takeaway	Choose one intake path, inspect the result, and preserve explicit human decisions.
group-title-0	PREPARE AND CHOOSE
group-title-1	OPERATE AND REVIEW
Human + assistant	Human + assistant
Human + assistant	Agree on the work
Human + assistant	MCP calls -> API
Human + assistant	The assistant explains actions; a person supplies judgment.
Project and team	Project and team
Project and team	Inspect or create
Project and team	propose -> confirm cast
Project and team	Named roles and charters belong to the project.
Choose intake	Choose intake
Choose intake	Queue OR start now
Choose intake	do not start twice
Choose intake	Ready pickup is an alternative to an immediate start.
Human review	Human review
Human review	Read before deciding
Human review	run_review: boolean
Human review	MCP approve/decline is binary. Feedback uses other surfaces.
State and artifacts	State and artifacts
State and artifacts	Watch, list, read
State and artifacts	API -> MCP -> client
State and artifacts	Progress and results return through the MCP adapter.
Coordinator	Coordinator
Coordinator	Runs and child work
Coordinator	status / children / watch
Coordinator	Queued: claim then unattended. Direct: no outcome gate.
e0	prepare
e1	choose
e2	start once
e3	observe
e4	inspect
note	Define Outcome is the third start variant: draft, obtain authorized confirmation, then dispatch.
n0	The assistant explains actions; a person supplies judgment.
n1	Named roles and charters belong to the project.
n2	Ready pickup is an alternative to an immediate start.
n3	MCP approve/decline is binary. Feedback uses other surfaces.
n4	Progress and results return through the MCP adapter.
n5	Queued: claim then unattended. Direct: no outcome gate.
groups	PREPARE AND CHOOSE; OPERATE AND REVIEW