CLI, Custom Agents, and MCP Servers

CLI, Custom Agents, and MCP Servers

GitHub Copilot CLI Configuration

The SDK uses Copilot CLI as its engine. Configuration is stored in ~/.copilot/ (or $XDG_CONFIG_HOME/copilot/):

• config.json - General configuration
• mcp-config.json - MCP server definitions

For full CLI documentation, see Using GitHub Copilot CLI.

Custom Agents

Custom agents are specialized configurations with tailored expertise for specific tasks.

See Creating Custom Agents and Custom Agents Configuration Reference.

Agent Profile Structure

Custom agents use Markdown files with YAML frontmatter:

---
name: my-agent
description: A specialized agent for specific tasks
tools: ["read", "edit", "search"]
target: github-copilot
mcp-servers:
  custom-mcp:
    type: 'local'
    command: 'mcp-server'
    args: ['--flag']
---

# Agent Instructions

Detailed behavioral instructions here (max 30,000 characters).

YAML Frontmatter Properties

Tools Configuration

Configure tool access:

• Enable all: Omit tools or use tools: ["*"]
• Enable specific: tools: ["read", "edit", "search"]
• Disable all: tools: []

Tool Aliases:

• execute - Run shell commands
• read - Access file contents
• edit - Modify files
• search - Find files/text (grep, glob)
• agent - Invoke other custom agents
• web - Web search/fetch

MCP Tool References: mcp-server-name/tool-name or mcp-server-name/*

Agent Storage Locations

• Repository: .github/agents/ directory
• Organization/Enterprise: Configured via GitHub settings
• System: CLI includes default agents

Priority (naming conflicts): System > Repository > Organization

MCP Server Integration

Model Context Protocol (MCP) servers extend Copilot's capabilities with external tools and resources.

See Enhancing Agent Mode with MCP and Setting up the GitHub MCP Server.

Default MCP Server

Copilot CLI comes with the GitHub MCP server pre-configured, enabling:

• Repository access and management
• Pull request operations
• Issue tracking
• GitHub workflow management

MCP Configuration Format

MCP servers are configured in ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "server-name": {
      "type": "local",
      "command": "mcp-server-command",
      "args": ["--arg1", "--arg2"],
      "env": {
        "API_KEY": "$COPILOT_MCP_API_KEY"
      }
    }
  }
}

Environment Variables in MCP Config

Supported patterns:

• $COPILOT_MCP_VAR
• ${COPILOT_MCP_VAR}
• ${{ secrets.COPILOT_MCP_VAR }}
• ${{ var.COPILOT_MCP_VAR }}