mcp-copilot-worker

A stdio MCP server that turns GitHub Copilot sessions into resumable background agents with task persistence, dependency-aware scheduling, optional fleet workers, and isolated workspaces.

Install

npx -y mcp-copilot-worker

Add it to Claude Code globally:

claude mcp add copilot-worker --scope user -- npx -y mcp-copilot-worker

Or configure any MCP client:

{
  "mcpServers": {
    "copilot-worker": {
      "command": "npx",
      "args": ["-y", "mcp-copilot-worker"]
    }
  }
}

Requirements

• Node 22+
• GitHub Copilot CLI installed and logged in

Log in first

copilot login
copilot -p "reply with exactly ok."

If the second command prints ok, the Copilot CLI profile is ready.

For multi-profile failover, point COPILOT_CONFIG_DIRS at a comma-separated list of profile directories:

export COPILOT_CONFIG_DIRS="$HOME/.copilot,/path/to/second-profile"

Public MCP surface

Tools

• spawn-agent — create a background task and start a Copilot session
• message-agent — continue a previous session by spawning a continuation task with a new task ID
• cancel-agent — cancel one task, many tasks, or clear all tracked tasks
• answer-agent — answer a pending question and resume execution

Resources

• system:///status — current task and profile counts
• task:///all — all tracked tasks with status
• task:///{id} — live detail for one task
• task:///{id}/session — raw session output log

MCP task handlers

The server also wires the MCP task protocol handlers for list/get/result/cancel in src/index.ts.

spawn-agent fields

| field | type | default | description | |---|---|---|---| | prompt | string | required | detailed instructions for the agent | | agent_type | enum | "general" | coder | planner | researcher | tester | general | | model | string | runtime default | any live-allowed model for the active Copilot profile | | isolation_mode | enum | "shared" | shared | isolated | | fleet | boolean | off unless env/task enables it | opt-in parallel scout workers inside the Copilot session | | timeout | integer | 1800000 | max execution time in ms | | context_files | array | — | files to inject as task context | | depends_on | array | — | task IDs that must complete first | | labels | array | — | freeform tags | | cwd | string | process cwd | working directory |

Agent types and validation

| type | min prompt | extra rule | |---|---|---| | coder | 1000 chars | requires at least one context_files entry | | planner | 300 chars | — | | tester | 300 chars | — | | researcher | 200 chars | — | | general | 200 chars | — |

context_files are capped at 20 files, 200 KB each, 500 KB total.

Parallel execution

Launch multiple agents simultaneously with isolation_mode: "isolated" when they may edit overlapping files. The server prefers detached git worktrees under .worktrees/<task-id> and falls back to copied workspaces under .super-agents/workspaces/<task-id>.

[
  {"prompt": "implement auth module...", "isolation_mode": "isolated"},
  {"prompt": "implement payment module...", "isolation_mode": "isolated"},
  {"prompt": "write e2e tests...", "isolation_mode": "isolated"}
]

Fleet mode

Fleet mode is opt-in. Enable it per task:

{"prompt": "...", "fleet": true}

Or enable it globally:

export COPILOT_ENABLE_FLEET=1

When enabled, the session attempts session.rpc.fleet.start() and logs [fleet] started if the SDK/runtime supports it.

Model selection

Models are discovered live from the active Copilot profile. The schema advertises the latest allowed model IDs, the runtime resolves supported legacy aliases, and unsupported requests fail with the current allowlist. Manual exclusions currently include gpt-4.1 and claude-opus-4.6-fast.

State and storage

• task state: ~/.super-agents/<workspace-hash>.json
• output logs: <workspace>/.super-agents/<task-id>.output
• isolated workspaces: <git-root>/.worktrees/<task-id>/ or <cwd>/.super-agents/workspaces/<task-id>/

Active pending, waiting, running, and waiting_answer tasks reload as failed after restart. rate_limited tasks survive restart.

Runtime entrypoints

Use one of these local entrypoints:

• bin/mcp-copilot-worker.mjs
• node --import tsx src/index.ts
• npm run serve

node dist/src/index.js is not a supported local runtime path because of the upstream @github/copilot-sdk ESM-resolution issue.

Local development

npm install
npm run build
npm run test:unit
npm run smoke
npm run doctor -- --json

npm run test:unit includes two live task-protocol integration tests (test/task-protocol.test.ts) that drive the real Copilot CLI over stdio. They run by default on authenticated developer machines and are skipped automatically in CI (or whenever CI=true). Force-enable them anywhere with RUN_COPILOT_LIVE_TESTS=1, or force-skip locally with MCP_COPILOT_SKIP_LIVE=1.

For CLI-level MCP validation, use mcpc against bin/mcp-copilot-worker.mjs. The repo ships a ready-made harness under test/mcpc/:

bash test/mcpc/run-suite.sh          # baseline discovery + contract suite
bash test/mcpc/run-advanced-suite.sh # stateful continuation / cancel / fleet
bash test/mcpc/run-all.sh            # both suites back to back

See test/mcpc/README.md for session-first workflow, hypothesis features, and the repo-specific rules the harness enforces.

Architecture notes

Repo-grounded Copilot SDK onboarding notes live under copilot-mcp-v2/:

• 00-overview.md
• 01-session-lifecycle.md
• 02-pause-and-question-flow.md
• 03-output-streaming.md
• 04-profile-rotation.md
• 05-workspace-isolation.md
• 06-fleet-mode.md
• 07-crash-recovery.md
• 08-adapter-implementation.md

Troubleshooting

copilot -p "reply with exactly ok."   # verify login
npm run doctor -- --json               # check runtime health

Common issues:

• Copilot CLI not logged in
• Requested model not allowed for the active profile
• Testing the published package from inside the source repo instead of from a clean temp directory