# copilot-cloud-agent-mcp

MCP server that lets Claude (or any MCP client) drive the **GitHub Copilot cloud agent** via its REST API. You give it a prompt and a repo, it spins up a Copilot session in the cloud that researches, edits, and (optionally) opens a pull request — all without you touching github.com.

Built against the public-preview `agent-tasks` API (version `2026-03-10`).

## What it can do

| Tool | Endpoint | Purpose |
|---|---|---|
| `create_task` | `POST /agents/repos/{owner}/{repo}/tasks` | Kick off a new cloud-agent task |
| `list_tasks` | `GET /agents/[repos/.../]tasks` | List tasks (repo-scoped or global) |
| `get_task` | `GET /agents/[repos/.../]tasks/{task_id}` | Fetch one task + its sessions |
| `wait_for_task` | (polls `get_task`) | Block until task hits a terminal state |
| `list_known_models` | — | Show model strings accepted by the API |
| `get_org_permissions` | `GET /orgs/{org}/copilot/coding-agent/permissions` | Read org cloud-agent setting |
| `set_org_permissions` | `PUT  …/permissions` | Set `all` \| `selected` \| `none` |
| `list_org_enabled_repos` | `GET …/permissions/repositories` | List repos with access |
| `set_org_selected_repos` | `PUT  …/permissions/repositories` | Replace selected-repos list |
| `enable_repo_for_org` | `PUT  …/permissions/repositories/{id}` | Add one repo |
| `disable_repo_for_org` | `DELETE …/permissions/repositories/{id}` | Remove one repo |

## Auth

The `agent-tasks` endpoints require a **user-to-server token**:
- classic personal access token,
- fine-grained PAT with **Agent tasks: read & write** repo permission, or
- OAuth user token.

GitHub App installation tokens are **not** accepted.

Token resolution order at runtime:
1. `GITHUB_TOKEN` env var
2. `GH_TOKEN` env var
3. `gh auth token` (from the `gh` CLI)

Org-permission endpoints additionally need `admin:org` scope.

## Install (Claude Code)

One command — `uvx` fetches the latest commit from GitHub on every launch:

```bash
claude mcp add copilot-cloud-agent --scope user -- \
  uvx --from git+https://github.com/fvegiard/copilot-cloud-agent-mcp.git \
  copilot-cloud-agent-mcp
```

Verify:

```bash
claude mcp list | grep copilot-cloud-agent
# → copilot-cloud-agent: uvx --from git+… - ✓ Connected
```

## Install (Claude Desktop, Cursor, etc.)

Add to your client's `mcpServers` config:

```json
{
  "mcpServers": {
    "copilot-cloud-agent": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/fvegiard/copilot-cloud-agent-mcp.git",
        "copilot-cloud-agent-mcp"
      ]
    }
  }
}
```

## Quick example

Inside Claude, ask:

> Using copilot-cloud-agent, start a task on `fvegiard/learn-mcp` with prompt "Add a CHANGELOG.md and update README to link to it", then wait for it to finish and tell me the PR URL.

Claude will call `create_task`, then `wait_for_task`, then pull `artifacts[].data.global_id` out of the final task object.

## API reference

- [Copilot cloud agent overview](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent)
- [Using the cloud agent via the API](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/use-cloud-agent-via-the-api)
- [REST: agent tasks](https://docs.github.com/en/rest/agent-tasks/agent-tasks?apiVersion=2026-03-10)
- [REST: coding-agent management](https://docs.github.com/en/rest/copilot/copilot-coding-agent-management?apiVersion=2026-03-10)