Configuring copilot agent MCP

[pelikhan]

/scout

• research how to create a action yml file to configuration custom steps to run in the github copilot agent job. Collects docs url + critical information to leverage this feature

• add a "--mcp" flag to the "init" command that configures copilot agent with the gh-aw mcp: add gh-aw mcp server definition to mcps.json, add steps to install the extension in copilot steps

[github-actions]

Agentic Scout triggered by this issue.

[github-actions]

🔍 Scout Research Report

Executive Summary

Successfully researched GitHub Copilot Agent MCP configuration and custom setup steps. Found comprehensive documentation on creating copilot-setup-steps.yml workflow files and configuring MCP servers through JSON configuration in repository settings.

Click to expand detailed findings

Research Findings

1. Creating Custom Action YML Files for Copilot Agent

File Location & Structure

The custom setup workflow file must be placed at:

.github/workflows/copilot-setup-steps.yml

Key Requirements

• Job name MUST be copilot-setup-steps - This exact name is required for Copilot to recognize it
• The workflow runs BEFORE the Copilot agent starts working
• Must be merged into your default branch to take effect

Basic Template Structure

name: "Copilot Setup Steps"

# Trigger configuration for testing
on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    paths:
      - .github/workflows/copilot-setup-steps.yml

jobs:
  # Job name MUST be exactly "copilot-setup-steps"
  copilot-setup-steps:
    runs-on: ubuntu-latest
    
    # Set minimal permissions needed
    permissions:
      contents: read  # Required if you checkout code
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v5
      
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
      
      - name: Install dependencies
        run: npm ci

Customizable Settings

You can ONLY customize these properties (others will be ignored):

• steps - Define custom setup steps
• permissions - Set minimal required permissions
• runs-on - Specify runner (e.g., ubuntu-4-core for larger runners, or ARC scale sets for self-hosted)
• services - Configure service containers
• snapshot - Configure snapshots
• timeout-minutes - Maximum 59 minutes

Important Notes

• Only Ubuntu x64 Linux runners are supported (no Windows/macOS)
• Self-hosted runners are supported via Actions Runner Controller (ARC) scale sets
• The fetch-depth option of actions/checkout is automatically overridden for security
• If any setup step fails (non-zero exit code), Copilot skips remaining steps and continues

---

2. Configuring MCP Servers for Copilot Agent

Configuration Location

MCP servers are configured in two places:

1. Repository Settings (JSON format):

   • Navigate to: Repository → Settings → Copilot → Coding agent
   • Add JSON configuration in the MCP configuration section

2. Environment Secrets:

   • Navigate to: Repository → Settings → Environments
   • Create environment named copilot
   • Add secrets with prefix COPILOT_MCP_*

mcpServers JSON Structure

{
  "mcpServers": {
    "server-name": {
      "type": "local|http|sse",
      "command": "npx",
      "args": ["-y", "`@package/name`", "..."],
      "tools": ["tool1", "tool2"],
      "env": {
        "ENV_VAR": "COPILOT_MCP_SECRET_NAME"
      }
    }
  }
}

Required Keys (All Server Types)

• type - Must be "local", "http", or "sse"
• tools - Array of tool names to enable, or ["*"] for all tools

Local MCP Server Keys

• command (required) - Command to start the server (e.g., "npx", "docker")
• args (required) - Arguments array for the command
• env (optional) - Environment variables mapping

Remote MCP Server Keys (HTTP/SSE)

• url (required) - Server URL
• headers (optional) - HTTP headers (can reference secrets with $COPILOT_MCP_*)

Example: gh-aw MCP Server Configuration

For a custom MCP server like gh-aw:

{
  "mcpServers": {
    "gh-aw": {
      "type": "local",
      "command": "npx",
      "args": [
        "-y",
        "gh-aw-mcp",
        "server",
        "start"
      ],
      "tools": ["*"],
      "env": {
        "GITHUB_TOKEN": "COPILOT_MCP_GITHUB_TOKEN"
      }
    }
  }
}

---

3. Installing MCP Dependencies in Setup Steps

To ensure your MCP server dependencies are available, add installation steps to copilot-setup-steps.yml:

Example: Node.js-based MCP Server

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@v5
      
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
      
      - name: Install gh-aw extension globally
        run: npm install -g gh-aw-mcp

Example: Docker-based MCP Server

steps:
  - name: Pull MCP server Docker image
    run: docker pull your-org/gh-aw-mcp:latest

Example: Azure Authentication for MCP

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    environment: copilot
    steps:
      - name: Azure login
        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

---

4. Environment Variables & Secrets

Setting Environment Variables

1. Navigate to: Repository → Settings → Environments
2. Create or select the copilot environment
3. Add secrets under "Environment secrets"
4. MUST prefix all MCP secrets with COPILOT_MCP_

Example Secret Configuration

• Secret Name: COPILOT_MCP_GITHUB_TOKEN
• Referenced in JSON as: "GITHUB_TOKEN": "COPILOT_MCP_GITHUB_TOKEN"

Direct Environment Variables

You can also set string values directly:

"env": {
  "API_HOST": "(redacted)",
  "API_TOKEN": "COPILOT_MCP_API_TOKEN"
}

---

5. Testing & Validation

Validate Your MCP Configuration

1. Create a test issue in the repository
2. Assign it to Copilot
3. Wait for Copilot to react with 👀 and create a PR
4. Open the PR and find "Copilot started work" event
5. Click View session → ... → Copilot
6. Expand the Start MCP Servers step
7. Verify your MCP server tools are listed

Test Your Setup Steps

The workflow automatically runs when:

• You manually trigger it via Actions tab (workflow_dispatch)
• You push changes to the file
• You open a PR that modifies the file

---

6. Implementation Plan for gh-aw

Based on the research, here's how to implement the --mcp flag for the init command:

Step 1: Create copilot-setup-steps.yml

name: "Copilot Setup Steps"

on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@v5
      
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
      
      - name: Install gh-aw MCP server
        run: npm install -g gh-aw-mcp

Step 2: Create MCP Configuration JSON

{
  "mcpServers": {
    "gh-aw": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "gh-aw-mcp", "server", "start"],
      "tools": ["*"],
      "env": {
        "GITHUB_TOKEN": "COPILOT_MCP_GITHUB_TOKEN"
      }
    }
  }
}

Step 3: Set Up Environment

1. Create copilot environment
2. Add COPILOT_MCP_GITHUB_TOKEN secret

Step 4: Add to Repository via GitHub API

• Use GitHub API to configure the MCP JSON in repository settings
• POST to /repos/{owner}/{repo}/copilot/coding-agent/mcp (check latest API docs)

---

Recommendations

For the --mcp Flag Implementation

1. Generate copilot-setup-steps.yml

   • Template the file with Node.js setup
   • Include gh-aw installation step
   • Commit to .github/workflows/ directory

2. Configure MCP Server

   • Use GitHub API to set MCP configuration in repository settings
   • Include proper error handling for API failures
   • Provide clear user feedback about configuration status

3. Set Up Environment Secrets

   • Guide user to create copilot environment
   • Prompt for required secrets (like GitHub token)
   • Validate secret names have COPILOT_MCP_ prefix

4. Validation & Testing

   • Provide instructions for testing the setup
   • Include troubleshooting steps
   • Link to Copilot session logs for debugging

Best Practices

1. Security: Always use secrets for sensitive data, never hardcode
2. Permissions: Set minimal required permissions
3. Tool Allowlisting: Specify specific tools rather than ["*"] for better security
4. Testing: Always test setup steps in PR before merging to default branch
5. Documentation: Document required secrets and their purposes
6. Self-Hosted Runners: Consider ARC scale sets for accessing internal resources

---

Key Sources

1. Official GitHub Docs:

   • Customizing the development environment for GitHub Copilot coding agent
   • Extending GitHub Copilot coding agent with MCP
   • Creating custom agents

2. Microsoft Azure Integration:

   • Connect GitHub Copilot coding agent with Azure MCP Server
   • Azure MCP Server integration guide

3. Recent Updates:

   • Copilot coding agent now supports self-hosted runners (Oct 28, 2025)
   • ARC scale sets support for runs-on target

---

Suggested Next Steps

1. Design the CLI interface for the --mcp flag
2. Implement file generation for copilot-setup-steps.yml
3. Integrate GitHub API calls to configure MCP settings
4. Add environment setup prompts for secrets
5. Create validation logic to test the configuration
6. Write comprehensive documentation with examples
7. Add error handling for common failure scenarios

AI generated by Scout for #2728

[pelikhan]

Use the information above to create a command to adds or update the steps to install the gh aw extension and create/update the MCP configuration to add the MCP-server command as MCP server