Implement tool use and environment interaction

2.1 Select and configure agent tools

Identify required tools

Agents act through tools: every file read, edit, shell command, API call or subagent invocation is a tool call. Choosing tools is choosing capability, so start from the task and add only what it needs.

Configure agent tools

In a custom agent profile, the tools property filters every tool available to the agent, built-in or from MCP servers. Its semantics are a classic exam target:

---
name: security-reviewer
description: Reviews changes for vulnerabilities and reports findings. Read-only; never edits code.
tools: ["read", "search", "github/*"]
---

Review the changes on this branch for injection, secrets, unsafe deserialization and
missing authorization checks. Report each finding with file, line and a suggested fix.
Do not modify files.

Configure agent tool permissions

"Which tools exist" and "which tools may run without asking" are separate questions, and each surface answers them differently.

2.2 Configure MCP servers

The Model Context Protocol is an open standard for connecting AI clients to tools. Instead of a one-off integration per system, a client talks to an MCP server that exposes tools in a structured format and performs the real action against the underlying service. Three concepts work together:

• An MCP server exposes tools — locally (a process on your machine, stdio) or remotely (hosted, http/sse).
• An MCP registry makes approved servers discoverable.
• An allowlist policy decides which servers may actually run.

flowchart LR
  subgraph GOV["Organization and enterprise policy"]
    direction LR
    REG["MCP registry<br/>catalogue of approved servers"] --> CLIENT["MCP client<br/>IDE · Copilot CLI"]
    ALLOW["Allowlist policy<br/>MCP servers in Copilot · managed settings"] --> CLIENT
  end
  CLIENT --> SERVER["MCP server<br/>local stdio or remote HTTP"]
  SERVER --> SYS["Underlying system<br/>GitHub · Sentry · Azure · Jira"]

Add an MCP server as a tool to an agent

In the repository JSON, type and tools are required for every server. Local servers need command and args; remote servers need a url and optional headers. Secrets are never pasted in: create an Agents secret whose name starts with COPILOT_MCP_ and reference it as $COPILOT_MCP_NAME, ${COPILOT_MCP_NAME} or ${COPILOT_MCP_NAME:-default}.

{
  "mcpServers": {
    "sentry": {
      "type": "local",
      "command": "npx",
      "args": ["@sentry/mcp-server@latest", "--host=$SENTRY_HOST"],
      "tools": ["get_issue_details", "search_issues"],
      "env": {
        "SENTRY_HOST": "https://contoso.sentry.io",
        "SENTRY_ACCESS_TOKEN": "$COPILOT_MCP_SENTRY_ACCESS_TOKEN"
      }
    },
    "docs": {
      "type": "http",
      "url": "https://docs.contoso.com/mcp",
      "tools": ["search_docs"],
      "headers": { "Authorization": "Bearer $COPILOT_MCP_DOCS_TOKEN" }
    }
  }
}

---
name: incident-triage
description: Correlates production errors with recent commits
tools: ["read", "search", "sentry/get_issue_details"]
mcp-servers:
  sentry:
    type: local
    command: npx
    args: ["@sentry/mcp-server@latest"]
    tools: ["*"]
    env:
      SENTRY_ACCESS_TOKEN: ${{ secrets.COPILOT_MCP_SENTRY_TOKEN }}
---

Find the Sentry issue referenced in the task and identify the commit most likely to have caused it.

Configurations combine in a fixed order, each level able to override the one before. An agent can use MCP tools configured in its own profile and in repository settings.

flowchart LR
  OOB["1 · Out-of-the-box servers<br/>GitHub MCP · Playwright MCP"] --> AGENT["2 · Custom agent profile<br/>mcp-servers property"]
  AGENT --> REPO["3 · Repository settings<br/>Settings → Copilot → MCP servers"]
  REPO --> EFFECTIVE["Effective configuration<br/>later levels override earlier ones"]

To confirm servers started, open the cloud agent session log, expand the Start MCP Servers step and look for their tools. Servers that need extra runtimes (for example uv or pipx) need those installed in copilot-setup-steps.yml.

Configure the GitHub remote MCP server

The GitHub MCP server gives agents GitHub data — repositories, issues, pull requests, Actions runs, code scanning alerts. It comes in two forms: the remote server hosted by GitHub at https://api.githubcopilot.com/mcp/ (recommended for most users) and a local server you run yourself (the ghcr.io/github/github-mcp-server image). GitHub Enterprise Server supports only the local server.

The default toolsets are repos, issues and pull_requests; others such as actions, code_security and secret_protection are opt-in.

// .vscode/mcp.json — the remote GitHub MCP server in VS Code
{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Inside Copilot cloud agent

Cloud agent gets the GitHub MCP server automatically, connected with a specially scoped token that has read-only access to the current repository only. To give it wider access — for example, to read issues in another repository — configure the server yourself in repository MCP settings with a PAT or a GitHub App, preferably still on the /readonly URL, and store the credential as a COPILOT_MCP_ Agents secret.

{
  "mcpServers": {
    "github-mcp-server": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/readonly",
      "tools": ["*"],
      "headers": {
        "X-MCP-Toolsets": "repos,issues,pull_requests,actions,code_security"
      }
    }
  }
}

Configure MCP registries

A registry is a catalogue of MCP servers. IDEs use the GitHub MCP Registry by default; an organization or enterprise can point Copilot at a custom registry so developers discover a curated set of approved servers. A custom registry can be self-hosted (fork the open-source MCP Registry, run it in Docker, or build your own) or provided by Azure API Center with anonymous read access. It must follow the v0.1 registry specification:

GET /v0.1/servers
GET /v0.1/servers/{serverName}/versions/latest
GET /v0.1/servers/{serverName}/versions/{version}

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type

Enter the registry's base URL in the Copilot policies (enterprise: AI controls → MCP; organization: Settings → Copilot → Policies). For Azure API Center, give the base URL only — not /v0.1/servers.

Configure MCP allow lists

Organizations have three levers, from coarse to fine:

1. The "MCP servers in Copilot" policy decides whether MCP servers can run at all in Copilot clients for Business and Enterprise users.
2. Registry-based restriction — "Restrict MCP access to registry servers": Allow all (any server) or Registry only (only servers in the configured registry; even local servers must be listed, with exactly matching IDs). The policy applies immediately.
3. managed-settings.json allowlists — allowedMcpServers and deniedMcpServers, matching servers securely by name, URL or exact stdio command. This is the method GitHub now recommends.

{
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverCommand": ["npx", "@playwright/mcp@latest"] }
  ],
  "deniedMcpServers": [
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/"] }
  ]
}

Managed-settings evaluation is strict and predictable:

1. Built-in default servers (such as the GitHub MCP server) are always allowed.
2. A server matching any deniedMcpServers entry is blocked — deny beats allow.
3. If allowedMcpServers exists, anything not matching it is blocked.
4. A URL or command containing an unresolved variable is blocked, because it cannot be verified.
5. A malformed list is treated as an empty allowlist — everything except built-ins is blocked.

2.3 Integrate agents within development environments

Evaluate the execution context

Execution context is the set of constraints that define where an agent runs and what it can reach: the repository, the branch, the workflow or machine it runs on, and the permissions it holds. It determines both visibility and capability.

Scope an agent to a specific repository

Repository scope is the first boundary. Copilot cloud agent can only change the repository specified when the task starts — it cannot change several repositories in one run — and by default it can only read context (issues, past PRs) from that repository through its GitHub MCP token.

• Availability — for Business and Enterprise, an administrator enables the cloud agent policy (disabled by default); organization owners can opt out some or all repositories; Pro, Pro+ and Max users have it on by default.
• Per-repository configuration — Settings → Copilot → Cloud agent (validation tools, workflow approval), MCP servers, Internet access (firewall), Memory.
• Custom agents — a profile in .github/agents/ applies to that repository; organization and enterprise profiles live in the agents/ folder of a .github or .github-private repository. On a name conflict, the lowest level wins: repository over organization over enterprise.

Configure an agent to be invoked in a CI workflow

Inside a workflow, the workflow is the execution boundary: the trigger, the runner, the permissions block and the secrets define everything the agent can do. There are three ways in:

flowchart TB
  TRIG["Trigger<br/>schedule · workflow_dispatch · pull_request"] --> JOB
  subgraph JOB["Workflow job — the execution boundary"]
    direction TB
    CO["Checkout"] --> INST["Install Copilot CLI<br/>npm install -g @github/copilot"]
    INST --> RUN["copilot -p prompt<br/>--allow-tool · --no-ask-user · -s"]
    RUN --> OUT["Publish result<br/>step summary · artifact · safe output"]
  end

name: Nightly repository summary
on:
  schedule:
    - cron: '30 17 * * *'
  workflow_dispatch:

permissions:
  contents: read
  copilot-requests: write      # lets GITHUB_TOKEN make Copilot requests (org billing)

jobs:
  summary:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v7
      - run: npm install -g @github/copilot
      - name: Summarize today's changes
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          copilot -p "Summarize today's commits on main as a bullet list in summary.md" \
            -s --no-ask-user \
            --allow-tool='shell(git:*)' --allow-tool='write(summary.md)'
          cat summary.md >> "$GITHUB_STEP_SUMMARY"

copilot --agent security-reviewer \
  -p "Review the diff against main for vulnerabilities" \
  -s --no-ask-user --allow-tool='shell(git:*)'

Authentication options for the CLI in Actions:

• GITHUB_TOKEN — recommended in organization repositories: short-lived, no stored secret, usage billed to the organization. Requires the policy Allow use of Copilot CLI billed to the organization and copilot-requests: write in permissions.
• A fine-grained PAT with the Copilot Requests permission, stored as an Actions secret and passed as COPILOT_GITHUB_TOKEN — the CLI-specific variable, so Copilot's access can differ from the workflow's GITHUB_TOKEN. Usage is billed to the PAT owner's seat.

Configure an agent to use branch-based scope

• Cloud agent creates a new copilot/ branch for its work and can only push to that single branch. When triggered by @copilot on an existing PR, it gets write access to that PR's branch instead.
• You can choose the base branch when starting a task from the Agents tab or panel, so the working branch is cut from, and the PR targets, something other than the default branch.
• The agent is subject to the repository's branch protections and required checks like any contributor.
• In CI, the workflow determines the branch — the agent runs in the checked-out ref.
• Custom agents define focus, tools and behaviour; they do not control branch creation, PR behaviour or execution isolation — that is always the execution context's job.

Enable autonomous actions: branches and pull requests

1. Enable the agent — policy for Business/Enterprise, and the repository not opted out.
2. Give it a task — assign an issue to Copilot (it reacts 👀 and opens a draft PR), prompt it from the Agents tab, mention @copilot on a PR, delegate from the CLI with /delegate or an & prefix, or call the API.
3. Let it work — it researches, plans, creates the branch, commits and pushes, validating with tests and linters in its environment.
4. Create the pull request — sessions started from the Agents tab do not open a PR automatically; click Create pull request when satisfied, or ask for one in the prompt. Issue assignment and /delegate open a draft PR.
5. Review and merge — a human marks it ready, approves and merges. Copilot cannot mark it ready for review, approve it or merge it.

Handle environment-specific constraints

Cloud agent can discover and install dependencies by trial and error, but that is slow, non-deterministic and fails for private packages. Make the environment deterministic with a Copilot setup steps workflow.

name: "Copilot Setup Steps"
on:
  workflow_dispatch:
  push:
    paths: [.github/workflows/copilot-setup-steps.yml]
  pull_request:
    paths: [.github/workflows/copilot-setup-steps.yml]

jobs:
  copilot-setup-steps:          # MUST be named exactly this
    runs-on: ubuntu-latest      # or a larger / self-hosted / Windows runner label
    timeout-minutes: 30         # maximum 59
    permissions:
      contents: read            # Copilot gets its own token for its work
    steps:
      - uses: actions/checkout@v7
        with:
          lfs: true
      - uses: actions/setup-node@v7
        with:
          node-version: "24"
          cache: "npm"
      - run: npm ci

• The file must contain a single job named copilot-setup-steps, and it only takes effect once it is on the default branch.
• Only steps, permissions, runs-on, services, snapshot and timeout-minutes (max 59) can be customized; anything else is ignored.
• If a step exits non-zero, the remaining setup steps are skipped and Copilot starts work with the environment as it is.
• Any fetch-depth you set on actions/checkout is overridden so the agent can roll back commits on request.
• The workflow's GITHUB_TOKEN is used by the setup steps only; Copilot receives its own token for the session.

The agent firewall

By default cloud agent's internet access is limited by a firewall, which reduces the risk of code or secrets being exfiltrated by unexpected behaviour or injected instructions. GitHub hosts are always reachable; a recommended allowlist (OS package repositories, container registries, language package registries, certificate authorities, Playwright browser downloads) is on by default. Blocked requests appear as a warning in the PR.

• Organization owners set Enable firewall and Recommended allowlist to Enabled, Disabled or Let repositories decide (the default), control whether repositories may add custom rules, and maintain an organization custom allowlist that repositories cannot remove.
• Allowlist entries are domains (the domain and its subdomains) or URLs (scheme, host and path prefix).
• Limitations: it applies only to processes the agent starts through its shell tool — not to MCP server processes or setup-step processes — only inside the Actions appliance, and sophisticated attacks may bypass it. It is a mitigation, not a complete security boundary.

2.4 Operate agents with safe execution paths and robust error handling

Reliable systems assume failure: agents misread tasks, tests fail, changes collide. The architecture should detect failure early, contain it, and hand it to a person with enough context to act.

flowchart TB
  FAIL["Required check fails"] --> RETRY{"Attempts < 2?"}
  RETRY -->|"yes"| FIX["Agent revises the branch<br/>and re-runs checks"]
  FIX --> FAIL2{"Green?"}
  FAIL2 -->|"yes"| REVIEW["Human review and merge"]
  FAIL2 -->|"no"| RETRY
  RETRY -->|"no"| ESC["Escalate<br/>what failed · what was tried · evidence · next step"]
  ESC --> HUMAN["Human decides<br/>fix · close PR · revert"]

Implement error handling

• Fail fast in workflows — leave continue-on-error false, use set -euo pipefail in scripts, and never let a failed agent step be reported as green.
• Log meaningfully — ::error:: annotations, step summaries and uploaded logs rather than silent failure.
• Prevent partial changes — work on a branch so an aborted run leaves nothing on the default branch.
• Hook into errors — the errorOccurred hook fires on agent errors (logging, alerting), and postToolUseFailure can add recovery guidance for the model after a failed tool call.

Implement retries

Retry transient failures — a network blip, a flaky runner — a bounded number of times, with backoff. Do not retry deterministic failures (a real test failure, a security block): that only burns time and AI credits.

- name: Run agent task with bounded retries
  run: |
    for attempt in 1 2 3; do
      if copilot -p "Fix the failing unit tests" -s --no-ask-user \
           --allow-tool='shell(npm:*)' --allow-tool=write; then
        exit 0
      fi
      echo "::warning::Attempt $attempt failed"
      sleep $((attempt * 10))
    done
    echo "::error::Agent failed after 3 attempts — escalating"
    exit 1

• Copilot CLI autopilot has --max-autopilot-continues to cap automatic continuations; set it explicitly in automation.
• An agentStop hook that keeps forcing continuation is overridden after 8 consecutive blocks — a runaway guard.
• A common team policy: if the same required check fails twice, stop iterating and escalate.

Implement rollbacks

CLI rewind restores only the files Copilot changed, skips files you edited since, and cannot restore files over 10 MB or turns that changed more than 500 files.

Implement escalation paths

• Required review — every agent PR reaches a human; CODEOWNERS auto-requests the right one.
• Notify on failure — an if: failure() step that opens an issue or pings maintainers with the run link.
• Deny with a reason — a preToolUse hook denies a risky tool call and returns permissionDecisionReason, which is surfaced for a human to act on.
• Steer or stop — follow-up prompts on the Agents page, or Stop session.
• A clear escalation report — what failed, what was attempted, what evidence exists, and the suggested next step.

- name: Escalate to maintainers
  if: failure()
  env:
    GH_TOKEN: ${{ github.token }}
  run: |
    gh issue create \
      --title "Agent run ${{ github.run_id }} needs a human" \
      --label needs-human \
      --body "Failed step logs: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"

Implement traceability and accountability