[BUG] Top-level custom agents (via --agent / agent setting) do not receive MCP tools; tools: frontmatter ignored

What's Wrong?

Custom agents running as the top-level session agent (via claude --agent <name> or "agent" in .claude/settings.json) have no MCP tools in their tool inventory. MCP servers are connected, their instructions appear in the system prompt, and WaitForMcpServers returns ready: true, but zero mcp__* tools are available.

The tools: frontmatter is completely ignored for enumerated lists. Listing Glob, Grep, MultiEdit, ToolSearch explicitly has no effect. The agent always gets the same 7 hardcoded tools: Read, Bash, Write, Edit, Agent, WebSearch, WebFetch.

The only configuration that provides MCP access is tools: "*" (wildcard).

Related to #13898, #25200, #30280, but distinct: those track subagents spawned via the Agent tool. This affects the top-level session agent.

What Should Happen?

The docs state:

"Subagents inherit the internal tools and MCP tools available in the main conversation by default."

"The mcpServers field applies in both contexts where an agent file can run: As a subagent, spawned through the Agent tool or an @-mention; As the main session, launched with --agent or the agent setting."

"If you keep all tools selected, the subagent inherits all tools available to the main conversation."

Expected:

1. Top-level custom agents should have access to MCP tools from configured servers
2. The tools: frontmatter should control which tools are available. Listed tools should actually be provided
3. When tools: is omitted, the agent should inherit all tools including MCP

Error Messages/Logs

No errors. Tools are silently absent. MCP server instructions are injected into the system prompt, but no mcp__* tools appear in the tool inventory.

Steps to Reproduce

1. Configure an MCP server

In ~/.claude.json:

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

Verify it works in a normal (non-custom-agent) session.

2. Create a custom agent

.claude/agents/test-mcp.md:

---
name: test-mcp
description: Test agent for MCP tool access
---

List all tools you have access to. Report whether you have any mcp__* tools, ToolSearch, and your complete tool list.

3. Set as top-level agent and start a session

.claude/settings.json:

{ "agent": "test-mcp" }

claude

Result: Agent reports 7 tools only. No MCP tools, no ToolSearch, no Glob/Grep.

4. Test matrix (all tested on v2.1.169)

| # | tools: | disallowedTools: | MCP tools? | ToolSearch? | Glob/Grep/MultiEdit? |
|---|---|---|---|---|---|
| 1 | Enumerated list | [NotebookEdit] | NO | NO | NO (despite being listed) |
| 2 | Enumerated + ToolSearch | [NotebookEdit] | NO | NO | NO |
| 3 | "*" (wildcard) | _(none)_ | YES (~128 tools, all 7 servers) | NO | NO |
| 4 | _(omitted)_ | [NotebookEdit] | NO | NO | NO |
| 5 | "*" (wildcard) | [NotebookEdit] | YES (7 tools, 3 servers) | NO | NO |

Key findings:

• tools: "*" is the only configuration that provides MCP access
• Enumerated tools: lists are completely ignored. The agent gets 7 hardcoded tools regardless of what's listed
• Glob, Grep, MultiEdit, ToolSearch are absent in ALL configurations, including tools: "*"
• tools: "*" without disallowedTools surfaced ~128 MCP tools across all 7 servers. Adding disallowedTools reduced this to 7 MCP tools across 3 servers, suggesting it triggers a different code path
• MCP server instructions are always injected into the system prompt regardless of tool availability

Is this a regression?

I don't know

Claude Code Version

2.1.169 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Warp

Additional Information

Relation to existing issues

| Issue | Status | Distinction |
|---|---|---|
| #13898 | Closed (staff: "fixed in 2.1.116+") | Subagents only |
| #25200 | Closed (dup of #13898) | Subagents only |
| #38920 | Closed (dup of #25200) | Subagents only |
| #30280 | Open | Subagents only. Workarounds there (explicit ToolSearch + MCP names, disallowedTools-only) do NOT work for top-level agents |
| #47733 | Open | Worktree-specific variant |

Root cause hypothesis

Per community analysis in #25200 (potterdigital):

"Custom agents use CUSTOM_AGENT_DISALLOWED_TOOLS, which does not include ToolSearchTool. Built-in agents use ASYNC_AGENT_ALLOWED_TOOLS, which explicitly includes ToolSearchTool and SkillTool."

The same hardcoded tool set appears to apply to top-level custom agents. The tools: frontmatter is parsed without error but not honored at runtime. tools: "*" bypasses this path, which is why it's the only working configuration.

Workaround

tools: "*" in frontmatter restores MCP access but still loses Glob, Grep, MultiEdit, and ToolSearch:

---
name: my-agent
description: Agent with MCP access
tools: "*"
---

Research and testing assisted by Claude Code. Findings and analysis are my own.