How to Connect MCP Servers to GitHub Copilot

To connect an MCP server to GitHub Copilot, you add the server to a configuration file for the Copilot surface you use. In VS Code, run MCP: Add Server and follow the prompts, or edit an MCP config file. In Copilot CLI, run /mcp add or copilot mcp add. For Copilot cloud agent on GitHub.com, paste a JSON config into your repository's Settings > Copilot > MCP servers page. Each surface uses a slightly different file and format, so this guide covers all three, step by step, based on GitHub's and VS Code's current docs.

What is an MCP server in GitHub Copilot?

MCP stands for Model Context Protocol. An MCP server gives Copilot extra tools it does not have out of the box, like querying a database, driving a browser or reading docs from another service. Has Brains explains MCP from the ground up at hasbrains.com.

One safety point first. VS Code warns that local MCP servers can run code with your permissions. Review the publisher, the command or URL, and the access a server asks for before you add it.

Where does the MCP config go for each Copilot surface?

Watch the key name. VS Code's own format uses servers, while the portable format used by Copilot CLI and cloud agent uses mcpServers. VS Code's docs warn not to copy between them without checking the format.

Also note a recent change. The VS Code guided flow now labels .vscode/mcp.json and the user-profile mcp.json as deprecated. They still work and are the only options that support input variables and per-server sandboxing.

How to connect an MCP server to Copilot in VS Code

This example adds the Playwright MCP server. It needs Node.js 18 or newer with npx.

1. Check your runtime:

node --version
npx --version

2. Open the Command Palette and run MCP: Add Server.
3. Choose Command (stdio) for a local command, or HTTP for a URL. For Playwright, enter:

npx -y @playwright/mcp@latest

4. Enter a unique server ID, such as playwright.
5. For personal use, choose Global, then Copilot Global. This writes to ~/.copilot/mcp-config.json.
6. Review any trust or sign-in prompts. Never paste credentials into chat or commit them.
7. Test it. Send a low-risk prompt that names the server, then check that a tool from that server ran without errors.

You can also browse servers. Search @mcp in the Extensions view to open the MCP server gallery (Preview), then click Install, or Install in Workspace to share it with your project.

To turn individual tools on or off, use Chat: Open Customizations > Tools, or Configure Tools in a Local harness session.

Example: a shared .vscode/mcp.json with a secret

The VS Code format supports inputs, so teammates are prompted for their own API key instead of committing one. VS Code stores the value securely after the first start.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "perplexity-key",
      "description": "Perplexity API Key",
      "password": true
    }
  ],
  "servers": {
    "perplexity": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "server-perplexity-ask"],
      "env": {
        "PERPLEXITY_API_KEY": "${input:perplexity-key}"
      }
    }
  }
}

Example: the portable format

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Server fields include type (stdio, http or sse), command and args for local servers, url and headers for remote servers, and env. The envFile field only works in the VS Code format.

Reuse servers you already set up elsewhere

VS Code can discover MCP servers configured in other apps. The chat.mcp.discovery.enabled setting controls which sources it reads. Discovery from GitHub Copilot CLI is on by default. Other sources are off by default.

How to add an MCP server to Copilot CLI

The GitHub MCP server is built into Copilot CLI, so you do not need to add it.

1. Start Copilot CLI and type /mcp add.
2. Enter a server name and pick Local/STDIO or HTTP/SSE.
3. Enter the command (local) or URL (remote). Tools default to *, meaning all tools.
4. Press Ctrl+S to save. The server is available right away, with no restart.

Or add it from your terminal:

# Local (stdio) server
copilot mcp add context7 -- npx -y @upstash/context7-mcp

# Remote (HTTP) server
copilot mcp add --transport http notion https://mcp.notion.com/mcp

Check it with /mcp show SERVER-NAME, which shows the server's status and tools. Use /mcp list, /mcp edit, /mcp disable and /mcp delete to manage servers.

How to connect MCP servers to Copilot cloud agent

Copilot cloud agent reads MCP servers from your repository settings. The same config also applies to Copilot code review.

1. Open your repository on GitHub.com and click Settings.
2. In the sidebar, under "Code, planning, and automation", click Copilot, then MCP servers.
3. Paste your JSON into the MCP configuration box.
4. Click Save MCP configuration. GitHub checks the syntax.
5. Add any secrets as Agents secrets or variables. Their names must start with COPILOT_MCP_.

Here is a config that follows GitHub's documented keys:

{
  "mcpServers": {
    "example-server": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "example-mcp@latest"],
      "env": {
        "EXAMPLE_API_KEY": "$COPILOT_MCP_EXAMPLE_API_KEY"
      },
      "tools": ["search_docs"]
    }
  }
}

Rules for the cloud agent config:

Test the cloud agent connection

Create an issue and assign it to Copilot. When the pull request appears, click View session, expand the Start MCP Servers step in the logs, and check that your tools are listed.

Cloud agent MCP limits

• The GitHub MCP server and the Playwright MCP server are on by default. The GitHub server gets a read-only token for the current repository.
• Only MCP tools work. Resources and prompts do not.
• Remote servers that use OAuth are not supported yet.
• Copilot uses configured tools on its own, without asking for approval. Keep the tools list tight.

Can a custom agent have its own MCP server?

Yes. A custom agent profile can define servers in an mcp-servers block and reference tools as server-name/tool-name. This works for cloud agent, but VS Code and other IDE custom agents ignore mcp-servers. If both define a server, GitHub processes the built-in config first, then the agent profile, then repository settings, and each later level can override the earlier one.

Why is my MCP server not working in Copilot?

• It does not appear or will not start: check the config scope, the runtime (for example Node.js) and the server output.
• Sign-in fails: check the publisher's auth steps and any organization restrictions.
• It runs but Copilot never calls it: name the server in your prompt and check the tool is enabled in the tools list.
• On a work account: for Copilot Business or Copilot Enterprise, the MCP servers in Copilot policy must be enabled. It is disabled by default.

Frequently asked questions

Where is the mcp.json file for GitHub Copilot in VS Code? The VS Code format lives in .vscode/mcp.json in your workspace or in your user profile. For personal servers, VS Code's guided flow now recommends Copilot Global, stored at ~/.copilot/mcp-config.json.

What is the difference between "servers" and "mcpServers"? servers is VS Code's own format. mcpServers is the portable format used by Copilot CLI, cloud agent and .mcp.json files. Check which one a file expects before you copy config between them.

Do I need to add the GitHub MCP server myself? Not for Copilot CLI or cloud agent. It is built into Copilot CLI and enabled by default for cloud agent. In VS Code, GitHub documents its remote URL as https://api.githubcopilot.com/mcp/.

Why can't I use MCP servers on my company's Copilot plan? On Copilot Business and Copilot Enterprise, an admin must enable the "MCP servers in Copilot" policy. It is off by default and does not apply to Free, Pro, Pro+ or Max.

How do I keep API keys out of my repo? Use inputs in .vscode/mcp.json, an envFile kept out of source control, or COPILOT_MCP_ Agents secrets for cloud agent. Never commit tokens or filled-in auth headers.

Can Copilot cloud agent use MCP resources and prompts? No. Cloud agent and code review only support MCP tools.

Keep learning

• Give an MCP server to a specialist with How to build a custom GitHub Copilot agent (step by step).
• Not sure which agent should use your server? Read Copilot agent mode vs Copilot coding agent: what's the difference?
• Learn agents and MCP hands-on in the free course GitHub Copilot Agents from Scratch.

Sources

• Add MCP servers in VS Code (VS Code Docs)
• MCP configuration reference (VS Code Docs)
• Extending GitHub Copilot Chat with MCP servers (GitHub Docs)
• Adding MCP servers for GitHub Copilot CLI (GitHub Docs)
• Configure MCP servers for your repository (GitHub Docs)
• Custom agents configuration (GitHub Docs)