Agentweaver

Appearance

Connect an MCP client ​

Connect GitHub Copilot CLI, GitHub Copilot desktop, VS Code, or Claude Desktop to Agentweaver through the hosted MCP endpoint.

Before you connect ​

  • Use a current client version that supports remote HTTP MCP servers and OAuth.
  • Sign in to the Agentweaver web app. On deployments that use Microsoft Entra ID, complete the Entra sign-in before authorizing the client.
  • In Agentweaver, open Account settings → MCP clients and copy the displayed URL. For a hosted deployment, the exact form is https://<deployment-origin>/mcp.

The /mcp path is required. Do not add a trailing slash, URL credentials, authorization headers, or query parameters.

How authorization works ​

Configure only the MCP URL for normal hosted use. On connection, the client:

  1. discovers the anonymous OAuth protected-resource metadata for /mcp;
  2. discovers Agentweaver's same-origin authorization server;
  3. opens a browser for Agentweaver sign-in when required;
  4. shows the signed-in Entra name and email/UPN (or an explicit Not signed in to Agentweaver page) before asking you to approve the least-privilege mcp:invoke scope; and
  5. completes authorization code + PKCE S256 and manages token refresh.

You do not copy or paste an Entra token, broker access token, API key, or other credential. The MCP client completes OAuth and keeps credentials out of URLs, commands, and checked-in configuration.

Install the Agentweaver Driver ​

GitHub Copilot clients work best with the Agentweaver Driver custom agent. Its definition includes the current MCP tool map and the safe playbooks for discovery, confirmation, run supervision, review, retries, and credential handling.

Every hosted Agentweaver deployment serves the definition without authentication from the same origin:

https://<deployment-origin>/agents/agentweaver.agent.md

For example, if the MCP URL is https://agentweaver.example.com/mcp, the agent definition is https://agentweaver.example.com/agents/agentweaver.agent.md.

For Copilot CLI, save it as a user-level agent:

powershell
$agentDirectory = Join-Path $HOME ".copilot\agents"
New-Item -ItemType Directory -Force $agentDirectory | Out-Null
Invoke-WebRequest `
  -Uri "https://<deployment-origin>/agents/agentweaver.agent.md" `
  -OutFile (Join-Path $agentDirectory "agentweaver.agent.md")
shell
install -d "$HOME/.copilot/agents"
curl --fail --proto '=https' --tlsv1.2 \
  --output "$HOME/.copilot/agents/agentweaver.agent.md" \
  "https://<deployment-origin>/agents/agentweaver.agent.md"

Review the downloaded definition, restart Copilot CLI, run /agent, and select agentweaver. You can also invoke it directly with copilot --agent=agentweaver --prompt "<your Agentweaver task>".

For VS Code or GitHub Copilot desktop, place the same file at .github/agents/agentweaver.agent.md in the repository where you will work, then select Agentweaver Driver from the agent picker. Agentweaver-created projects already receive this repository-level definition, so no separate install is needed there.

GitHub Copilot CLI ​

  1. Start an interactive Copilot CLI session and run /mcp add.
  2. Name the server agentweaver, choose HTTP, enter the MCP server URL, leave HTTP headers empty, and save.
  3. Complete the browser sign-in and consent flow.
  4. Run /mcp show agentweaver and confirm that the server is connected and its tools are listed.

The non-interactive equivalent is:

shell
copilot mcp add --transport http agentweaver https://<deployment-origin>/mcp

Do not add --header or put credentials in the command.

GitHub Copilot desktop ​

  1. Open Customize → MCP servers.
  2. Add a custom remote HTTP server named Agentweaver and enter the MCP server URL.
  3. Connect and complete the browser sign-in and consent flow.
  4. Start a session and confirm that Agentweaver tools appear in the tool picker.

GitHub manages this configuration surface, and labels can move between desktop releases. If the placement changes, search the Customize view for MCP servers; do not replace OAuth with a copied token. Select Agentweaver Driver from the agent picker after the repository-level definition is installed.

VS Code ​

  1. Open the Command Palette and run MCP: Add Server.
  2. Choose HTTP, enter the MCP server URL, and select the user or workspace configuration scope.
  3. Start the server and complete the browser sign-in and consent flow.
  4. Run MCP: List Servers and confirm that Agentweaver is running and exposes tools.
  5. Select Agentweaver Driver from the Copilot Chat agent picker after the repository-level definition is installed.

VS Code writes its client-managed mcp.json entry. No input variable or authorization header is required for Agentweaver OAuth.

Claude Desktop ​

  1. Open Customize → Connectors.
  2. Add a custom connector named Agentweaver.
  3. Enter the MCP server URL from Agentweaver Account settings.
  4. Open Advanced settings and enter agentweaver-claude as the OAuth Client ID. Leave OAuth Client Secret empty.
  5. Connect, complete browser sign-in and consent, then confirm that the connector lists Agentweaver tools.

Agentweaver registers agentweaver-claude as a public OAuth client for only Claude's exact hosted callback, https://claude.ai/api/mcp/auth_callback. Claude sends S256 PKCE on the authorization request, so no client secret, static authorization header, or manually copied token is used. URL-only setup is not supported because Agentweaver intentionally rejects HTTPS callbacks submitted through anonymous dynamic client registration.

Local repository development only ​

The hosted flow above is the supported onboarding path. A repository developer who intentionally launches apps/Agentweaver.Mcp over stdio does not have an HTTP browser callback and must supply an Agentweaver broker token through the process environment. This is for trusted local development and deterministic test harnesses only, not hosted client setup. Never place the token in command arguments, source control, or a URL. Raw Entra access tokens, GitHub tokens, and API keys are rejected.

GitHub capabilities after MCP sign-in ​

MCP sign-in authorizes Agentweaver tool calls. Repository and AI access are separate GitHub capabilities. Authorize each one only when a workflow needs it:

github_repo_app_connect → open browser_url → github_repo_app_authorization_status

The browser handoff is bound to the Entra identity that started it. If the browser does not have a current Agentweaver Entra session, Agentweaver first asks you to sign in, then resumes the same opaque handoff. This applies to Repo App and project Copilot App authorization. Do not open the URL in a browser signed in as another person. After GitHub finishes, Agentweaver identifies whether the completed action was repository or Copilot authorization, shows a success or error status, and tells you to return to the MCP client and poll the authorization status. OAuth state, callback cookies, GitHub codes, and credentials never appear on that page or in MCP output.

When a project Copilot binding is needed, a Project Owner completes project_copilot_app_connect → open browser_url → project_copilot_app_authorization_status and verifies project_github_capability_status. An eligible platform provider can supply project work without that binding; see Provider hierarchy. Handoff and polling return only opaque transaction identifiers and lifecycle state; credentials, OAuth state, installations, repositories, and permissions never appear in MCP output. The status response separates interactive_ready, unattended_ready, and repository_ready; its top-level status is one of those values, reauthorization_required, or unavailable. Do not treat interactive readiness as authority for a schedule, event, or heartbeat run.

If the client reports 401, reconnect the MCP server and complete the browser OAuth flow. Do not work around the failure by pasting a token into client settings.

Recommended entry points ​

  • Common case: run_task — one call that starts the run, polls, and returns artifacts or the next action.
  • Manual define-outcome control: coordinator_start(autopilot=false) → coordinator_outcome_spec_get → coordinator_outcome_spec_confirm (or revise) → observation → artifact inspection → review when gated.

When a composed workflow is waiting for fan-out children or parent continuation, run_task may return timed_out with the existing run ID, an empty artifacts array, and a progress hint, even if the embedded run's API status is awaiting_review. Inspect coordinator_work_plan_get / coordinator_children_get and poll that same ID with run_status; use run_watch only when a live stream is requested. This wait is not a human review gate; a workflow parent can have a fan work plan even when its run detail reports is_coordinator_plan: false. Call run_review only when the current run reports pending_request_kind: workflow_review: this is an advisory signal for a current, undecided review request with pinned output; approval is always manual and the review endpoint rechecks the gate. An absent or unknown kind is not evidence of human review, even if the run reports awaiting_review or a previous work plan is complete. Never repeat run_task to resume a run: it starts a new execution.

Poll vs. stream ​

  • Use run_status for quick snapshots.
  • run_status preserves the API's sandbox.current_binding projection. Use its verified claim and Pod UIDs for current ownership; the legacy sandbox pod and executor backend describe launch history, not a current preview.
  • Use run_watch only when the operator explicitly wants a live stream.
  • Tell the operator that run_watch blocks while waiting; that is expected, not a hang.

Timeout and retry protocol ​

If a tool returns -32001 Request timed out:

  1. Call diagnostics_get (or heartbeat_status).
  2. If the server looks healthy, retry once with brief backoff.
  3. Safe-to-retry tools are read-only calls such as run_status, coordinator_work_plan_get, coordinator_children_get, run_show_artifacts, and run_get_file.
  4. Do not blindly retry non-idempotent calls such as coordinator_start, run_task, run_review, or project_delete until you verify whether the first attempt already took effect.
  5. A timed-out GitHub-origin project_create may be retried with the same unexpired repository_selection_code. The server returns the same reserved project and its creating, active, or failed state rather than creating a duplicate workspace. Blank-project creation is not covered by this retry guarantee.

Run and project consistency ​

  • project_rename returns the updated project after the rename is persisted.
  • team_member_add uses the requested name when it is valid and available.
  • run_retry preserves whether the original Coordinator run used direct or defineOutcome start mode.
  • coordinator_work_plan_get returns null while no plan is available.
  • run_failure_diagnostic can report Coordinator failures that occur during assembly, including blocked assembly.
  • validate_blueprint accepts a blueprint that references the workflow supplied in its own generated_workflow_yaml.

Full workflow sequence ​

Manual end-to-end path:

project_list (or project_create) → confirm team → coordinator_start(autopilot=false) → coordinator_outcome_spec_get → coordinator_outcome_spec_confirm → run_status (poll) → [coordinator_steer if needed] → [run_show_artifacts → run_get_file → run_review if gated]

team_cast is proposal-only by default; confirm its proposal before dispatch. run_review accepts an approved boolean, not a request-changes payload. Use web/REST review for change-request feedback. memory_export is optional, not a required terminal step.

Common one-call path:

run_task

This starts a new run in direct mode by default; it is not a Ready-card pickup command. See the exact-tool lifecycle diagram.

Backlog flow ​

backlog_capture_task → backlog_move_to_ready (or send_all_backlog_to_ready) → heartbeat pickup

Heartbeat atomically claims the Ready item and reserves its coordinator run. Do not also call run_task or coordinator_start for the same queued task. Those are alternative explicit starts. Pickup autopilot controls unattended confirmation; it does not remove tool approvals or human merge review.

Results retrieval ​

Always call run_show_artifacts before run_get_file. The artifact list tells you which file paths are valid inputs for run_get_file.

Testing the MCP path ​

This section is for repository maintainers testing a deployment, not for client onboarding. Put the short-lived broker token in the process environment, never in command arguments or source control.

Run the deterministic CLI-to-MCP smoke test from the repository root:

powershell
$env:AGENTWEAVER_BASE_URL = "https://<staging-host>"
$env:AGENTWEAVER_TOKEN = "<agentweaver-broker-token>"
npm run test:mcp-smoke

The test discovers the live MCP tools (including project_delete), verifies their capability contract, creates a uniquely named project using a server-assigned workspace path and the software-development blueprint, submits a minimal run, polls for at most five minutes, confirms an outcome gate when needed, and requires an artifact. In finally, it archives the run and deletes only the project it created, including after failure, timeout, or cancellation. The primary failure remains separate from cleanup failures.

For local stdio testing, pass the server command explicitly:

powershell
npm run test:mcp-smoke -- --target stdio --server-command dotnet `
  --server-args '["run","--project","apps/Agentweaver.Mcp","--","--stdio"]' `
  --project-id <id> `
  --project-is-disposable

An explicit project ID is accepted only with --project-is-disposable; smoke archives its run but never deletes a caller-owned project. Without an ID, use AGENTWEAVER_SMOKE_PROJECT_NAME, AGENTWEAVER_SMOKE_WORKING_DIRECTORY, and AGENTWEAVER_SMOKE_BLUEPRINT_ID only to override creation defaults. Do not pass a local Windows path to a deployed AKS target.

HTTP targets must be absolute URLs with pathname exactly /mcp. Any HTTPS host is accepted; HTTP is loopback-only. URL credentials, fragments, /mcp/, and TLS bypasses are rejected. Sanitized preflight evidence records origin/path, auth source, project/run IDs, cleanup intent/result, and TLS mode without recording the token.