github / github/copilot-cli

Agent-level tools in .agend.md frontmatter is not enforced in Copilot CLI

Open
#2,638 1 comment 1 reaction 0 assignees View on GitHub
area:agents area:mcp
Dominant language
Shell
Stars
11.2k
Forks
1.9k
Avg merge
14h 16m
Merged PRs (30d)
6

Description

### Describe the bug

Agent-level `tools:` whitelist in `.agent.md` frontmatter is not enforced in Copilot CLI. The agent can call any tool from any loaded MCP server regardless of what's listed in `tools:`.

Additionally, the `tools:` filter inside `mcp-servers:` in an agent profile DOES work when the MCP server name is unique, but is silently ignored when the name conflicts with a server already defined in `~/.copilot/mcp-config.json`. The precedence between global and agent-level MCP configs is undocumented.

### Affected version

1.0.24-0

### Steps to reproduce the behavior

**Test 1: Top-level `tools:` — NOT enforced**
1. Configure an MCP server `my-mcp` in `~/.copilot/mcp-config.json` with `"tools": ["*"]`
2. Create `~/.copilot/agents/test-agent.agent.md` with `tools: ['my-mcp/search_code']`
3. Start session, `/agent test-agent`
4. Ask it to use a tool NOT in the `tools:` list (e.g. `search_workitem`)
5. It succeeds — the whitelist is not enforced

**Test 2: `tools:` inside `mcp-servers:` — WORKS with unique name**
1. In the agent, define a `mcp-servers:` block with a name NOT in global config
2. Set `tools: ['search_code']` on that server
3. Only `search_code` loads — this works correctly

**Test 3: Same MCP name in global AND agent — global wins silently**
1. Define `my-mcp` in both `~/.copilot/mcp-config.json` (with 5 specific tools) and the agent's `mcp-servers:` (with 1 different tool: `pipelines_get_builds`)
2. Start session with the agent
3. Only the global config's 5 tools load. The agent's `pipelines_get_builds` is not available. No warning.

**Test 4: Doc example pattern — top-level `tools:` NOT enforced**
1. Follow the exact pattern from the [docs](https://docs.github.com/en/copilot/reference/custom-agents-configuration#mcp-server-configuration-details):
```yaml
tools: ['tool-a', 'tool-b', 'my-mcp/search_code']
mcp-servers:
my-mcp:
type: 'local'
command: 'some-command'
args: ['--arg1']
tools: ["*"]
```
2. All tools from the MCP server are available — the top-level `tools:` restriction is ignored

### Expected behavior

1. The top-level `tools:` property should restrict which tools the agent can access, as documented at https://docs.github.com/en/copilot/reference/custom-agents-configuration#tools
2. When an MCP server name exists in both global config and an agent profile, there should be documented precedence (agent overrides global, or merge, or error) — not silent discard of the agent's definition
3. The `tools:` filter inside `mcp-servers:` should work regardless of whether the server name conflicts with global config

### Additional context

- OS: Windows 11
- Shell: PowerShell 7.x
- Terminal: Windows Terminal

Summary of findings:

| Mechanism | Documented | Actual CLI behavior |
|-----------|-----------|-------------------|
| Top-level `tools:` on agent | Restricts available tools | ❌ Ignored |
| `tools:` inside `mcp-servers:` (unique name) | Restricts server's tools | ✅ Works |
| `tools:` inside `mcp-servers:` (name conflicts with global) | Not documented | ❌ Global wins silently |
| Precedence: global vs agent MCP configs | Not documented | Global always wins |

This prevents building per-agent tool isolation — the primary use case for the `tools:` property. The filtering logic exists (it works for server-level `tools:` with unique names) but is not applied to the top-level `tools:` or to name-conflicting servers.

Relevant docs:
- https://docs.github.com/en/copilot/reference/custom-agents-configuration#tools
- https://docs.github.com/en/copilot/reference/custom-agents-configuration#mcp-server-configuration-details

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.