GitHub Copilot

Why this agent

GitHub Copilot (the VS Code extension flavour, distinct from GitHub Copilot CLI) is Microsoft’s AI peer programmer built into VS Code. Since VS Code 1.99 (April 2025), MCP support is native to VS Code itself — the Copilot Chat extension consumes the shared mcp.json config that any VS Code MCP host reads. Reference: microsoft/vscode-docs/docs/copilot/reference/mcp-configuration.md.

The same install snippet on this page also wires espctl into Continue, Cline, and any other VS Code MCP host you might have installed — VS Code is the registry, the extension is the consumer.

Prerequisites

• VS Code 1.99 or later with the GitHub Copilot Chat extension enabled and an active Copilot subscription.
• espctl installed at a stable path on disk.
• (Optional, for remote builds) the Aegis build server URL + MCP_AUTH_SECRET.

Install snippet (or alternative)

Create .vscode/mcp.json in your workspace root (or open the user-profile mcp.json via Command Palette: MCP: Open User Configuration):

{
  "servers": {
    "espctl": {
      "type": "stdio",
      "command": "/path/to/espctl",
      "args": ["mcp", "serve"],
      "env": {
        "CONTROL_BASE_URL": "https://esphome.cloud",
        "MCP_AUTH_SECRET": "your-access-key"
      }
    }
  }
}

Replace:

• /path/to/espctl — full path to your espctl executable.
• CONTROL_BASE_URL — your Aegis build server URL.
• MCP_AUTH_SECRET — the access key your build server gave you.

Or grab the same envelope pre-filled:

Read the install://github-copilot resource.

VS Code picks up the config on save; no reload required. To verify or restart a specific server, open Command Palette → MCP: Show Installed Servers.

First-run verification

Open Copilot Chat (kbd Ctrl+Alt+I on Windows/Linux, Cmd+Ctrl+I on macOS) and ask:

What espctl tools do you have?

Expected: Copilot lists ~40 espctl tools and offers to run them (each tool invocation gets a confirmation prompt by default).

Troubleshooting

• VS Code shows “MCP server failed to start” — VS Code’s Output panel has an “MCP” channel; open it for the actual subprocess stderr. Most common cause is a wrong absolute path for command.
• Tools listed but every call returns “auth required” — MCP_AUTH_SECRET is missing or has been revoked. Get a fresh access key from the control plane and paste it into the config.
• Want to put the secret in VS Code’s secret store instead of plain env? VS Code mcp.json supports inputs: arrays for prompted values:

  {
    "inputs": [
      { "type": "promptString", "id": "mcp-auth-secret", "description": "Aegis MCP auth", "password": true }
    ],
    "servers": {
      "espctl": {
        "type": "stdio",
        "command": "/path/to/espctl",
        "args": ["mcp", "serve"],
        "env": { "MCP_AUTH_SECRET": "${input:mcp-auth-secret}" }
      }
    }
  }
  

• Want HTTP transport? Replace type:"stdio" + command block with type:"http", url:"https://esphome.cloud/mcp/esp-idf", and headers: { "Authorization": "Bearer ${input:mcp-auth-secret}" }.
• Want sandboxing? Add sandboxEnabled: true + a sandbox: block (macOS/Linux only) with filesystem.allowWrite and network.allowedDomains. See VS Code MCP docs for the full schema.

Tested as-of 2026-05-19

GitHub Copilot (VS Code) -specific notes

• VS Code MCP is shared across all MCP-host extensions — once espctl is in mcp.json, Continue, Cline, Roo Code, and any other VS Code MCP host see it too. No need for per-extension install:// arms in this matrix.
• Workspace mcp.json (.vscode/mcp.json) is checked into git by default; user-profile mcp.json is per-machine. For projects that want espctl ESP-IDF-only, prefer workspace scope; for an “always available” Copilot tool, prefer user scope.
• The Copilot CLI (copilot-cli) is a separate product with its own evolving MCP story — see Copilot CLI.
• Cursor reuses VS Code’s editor surface but NOT its MCP config — Cursor has its own .cursor/mcp.json (already covered by Cursor in this matrix).