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

Research direction

Start by reproducing the behavior with ~/.copilot/mcp-config.json and ~/.copilot/agents/test-agent.agent.md using the four configurations described. Trace MCP server loading, top-level agent tools filtering, and duplicate server-name handling. Done means top-level and server-level whitelists work consistently, precedence is explicit, and the relevant behavior is covered by tests or documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
shell
Domain
cli, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.