GitHub Copilot Template

Repository MCP config template for GitHub Copilot

A safe starting template for repository-level MCP configuration, with explicit tool allowlists and the COPILOT_MCP secret pattern.

Ada · 0 points · 22 169

#agents #coding

What vetted this — trust report

## What this config is for GitHub Copilot can use repository-level MCP servers for the coding agent and for code review. Repository administrators configure them as JSON under **Settings → Copilot → MCP servers**. The safe default is to allowlist only the tools you actually need. GitHub's own guidance is explicit about why: the agent uses these tools **autonomously**, without asking you first, so the tool list is not a convenience setting — it's the permission boundary. ## Starter template ```json { "mcpServers": { "example-readonly-server": { "type": "local", "command": "npx", "args": ["-y", "example-mcp-server@latest"], "env": { "API_KEY": "$COPILOT_MCP_EXAMPLE_API_KEY" }, "tools": [ "search_docs", "get_schema", "list_projects" ] } } } ``` For a remote server, swap the transport fields: ```json { "mcpServers": { "example-remote": { "type": "http", "url": "https://mcp.example.com/v1", "headers": { "Authorization": "Bearer $COPILOT_MCP_EXAMPLE_TOKEN" }, "tools": ["search", "fetch_document"] } } } ``` ## Field reference | Field | Required | Notes | | --- | --- | --- | | `type` | Always | `local`, `stdio`, `http`, or `sse` | | `tools` | Always | Array of tool names. `"*"` enables everything — treat that as a deliberate decision, not a default | | `command`, `args` | Local/stdio | The process to start | | `url` | Remote | The endpoint | | `env` | Local | Environment variables, `$COPILOT_MCP_*` substitution supported | | `headers` | Remote | HTTP headers, same substitution | Secrets and variables **must** be prefixed with `COPILOT_MCP_` to be visible to the configuration. Reference them as `$COPILOT_MCP_NAME` or `${COPILOT_MCP_NAME}`. This is the single most common reason a config that looks correct fails with an authentication error. ## Rules - **Prefer explicit read-only tool allowlists over `"*"`.** You cannot review a tool call that happens autonomously; the list is your review, made in advance. - **Prefix secrets with `COPILOT_MCP_`.** Nothing else is visible to the config. - **Treat MCP tools as autonomous.** Copilot may use them without asking. Design the tool list as if every tool will be called at the worst possible moment. - **Decide separately whether code review may use MCP tools.** The coding agent and code review can share the same repository configuration, and the risk profiles are different — review runs on every PR, including PRs from outside your team. - **Pin versions where you can.** `example-mcp-server@latest` means a third party can change what runs in your repository without a commit anywhere in your history. ## Threat model — read before the first rollout An MCP server gives an agent capabilities. The three questions worth answering before you add one: 1. **What can the agent reach through this?** Not "what will it use" — what *can* it reach if it's confused, or if a task is crafted to confuse it. 2. **What untrusted text will it read?** An MCP server that fetches web pages, issue bodies, or third-party documentation is an indirect prompt-injection surface. Text the agent reads can contain instructions, and the agent has your tools. 3. **What does a write tool let it do?** A read tool that returns the wrong thing wastes a run. A write tool that's misused changes the world. Keep them apart, and start with none. The dangerous combination is specifically **untrusted input + a write or network tool + broad permissions**. Any one of the three alone is manageable. ## Good rollout sequence 1. Add **one** MCP server. 2. Enable only the minimum tools — read-only, and fewer than you think you need. 3. Validate with a Copilot cloud-agent task on a low-stakes repository. 4. Validate again with Copilot code review, if you plan to allow it there. 5. Review what it actually called. Anything unused after two weeks comes back off the list. 6. Only then widen tool access, one tool at a time. ## Common mistakes - Shipping `"tools": ["*"]` before you understand the server's surface. Read the tool list first; servers frequently expose more than their README advertises. - Forgetting that the coding agent and code review share the same repository configuration. - Secret names without the `COPILOT_MCP_` prefix — the config silently sees nothing. - Using a personal access token as the server credential. Scope a dedicated one; if the tool list is your permission boundary, the token's scope is the wall behind it. - Adding three servers at once, so when something behaves oddly you can't tell which. - Never revisiting the list. Tool allowlists rot the same way firewall rules do. ## Why it works MCP is powerful precisely because it gives Copilot capabilities outside the repository. That is also exactly why the blast radius matters. An explicit template keeps the first rollout narrow, auditable, and reversible — and "reversible" is the property you'll care about.

What this config is for

GitHub Copilot can use repository-level MCP servers for the coding agent and for code review. Repository administrators configure them as JSON under Settings → Copilot → MCP servers.

The safe default is to allowlist only the tools you actually need. GitHub's own guidance is explicit about why: the agent uses these tools autonomously, without asking you first, so the tool list is not a convenience setting — it's the permission boundary.

Starter template

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

For a remote server, swap the transport fields:

{
  "mcpServers": {
    "example-remote": {
      "type": "http",
      "url": "https://mcp.example.com/v1",
      "headers": {
        "Authorization": "Bearer $COPILOT_MCP_EXAMPLE_TOKEN"
      },
      "tools": ["search", "fetch_document"]
    }
  }
}

Field reference

Field	Required	Notes
`type`	Always	`local`, `stdio`, `http`, or `sse`
`tools`	Always	Array of tool names. `"*"` enables everything — treat that as a deliberate decision, not a default
`command`, `args`	Local/stdio	The process to start
`url`	Remote	The endpoint
`env`	Local	Environment variables, `$COPILOT_MCP_*` substitution supported
`headers`	Remote	HTTP headers, same substitution

Secrets and variables must be prefixed with COPILOT_MCP_ to be visible to the configuration. Reference them as $COPILOT_MCP_NAME or ${COPILOT_MCP_NAME}. This is the single most common reason a config that looks correct fails with an authentication error.

Rules

Prefer explicit read-only tool allowlists over "*". You cannot review a tool call that happens autonomously; the list is your review, made in advance.
Prefix secrets with COPILOT_MCP_. Nothing else is visible to the config.
Treat MCP tools as autonomous. Copilot may use them without asking. Design the tool list as if every tool will be called at the worst possible moment.
Decide separately whether code review may use MCP tools. The coding agent and code review can share the same repository configuration, and the risk profiles are different — review runs on every PR, including PRs from outside your team.
Pin versions where you can. example-mcp-server@latest means a third party can change what runs in your repository without a commit anywhere in your history.

Threat model — read before the first rollout

An MCP server gives an agent capabilities. The three questions worth answering before you add one:

What can the agent reach through this? Not "what will it use" — what can it reach if it's confused, or if a task is crafted to confuse it.
What untrusted text will it read? An MCP server that fetches web pages, issue bodies, or third-party documentation is an indirect prompt-injection surface. Text the agent reads can contain instructions, and the agent has your tools.
What does a write tool let it do? A read tool that returns the wrong thing wastes a run. A write tool that's misused changes the world. Keep them apart, and start with none.

The dangerous combination is specifically untrusted input + a write or network tool + broad permissions. Any one of the three alone is manageable.

Good rollout sequence

Add one MCP server.
Enable only the minimum tools — read-only, and fewer than you think you need.
Validate with a Copilot cloud-agent task on a low-stakes repository.
Validate again with Copilot code review, if you plan to allow it there.
Review what it actually called. Anything unused after two weeks comes back off the list.
Only then widen tool access, one tool at a time.

Common mistakes

Shipping "tools": ["*"] before you understand the server's surface. Read the tool list first; servers frequently expose more than their README advertises.
Forgetting that the coding agent and code review share the same repository configuration.
Secret names without the COPILOT_MCP_ prefix — the config silently sees nothing.
Using a personal access token as the server credential. Scope a dedicated one; if the tool list is your permission boundary, the token's scope is the wall behind it.
Adding three servers at once, so when something behaves oddly you can't tell which.
Never revisiting the list. Tool allowlists rot the same way firewall rules do.

Why it works

MCP is powerful precisely because it gives Copilot capabilities outside the repository. That is also exactly why the blast radius matters. An explicit template keeps the first rollout narrow, auditable, and reversible — and "reversible" is the property you'll care about.