Agent YAML mcpServers not available when spawned via Task tool
Resolved 💬 3 comments Opened Feb 23, 2026 by Eslamehassan Closed Mar 23, 2026
Bug Report
Description
MCP servers configured in an agent's YAML frontmatter (mcpServers field) are not injected/available when the agent is spawned via the Task tool (subagent). The agent reports zero MCP tools registered despite having them defined in its YAML.
Steps to Reproduce
- Create an agent definition at
.claude/agents/frontend-implement.mdwith an MCP server configured in the YAML frontmatter:
---
name: frontend-implement
description: Frontend implementation agent
mcpServers:
pencil:
command: /Applications/Pencil.app/Contents/Resources/app.asar.unpacked/out/mcp-server-darwin-arm64
args:
- "--app"
- "desktop"
type: stdio
---
- Spawn the agent via the Task tool (as a subagent)
- Ask the agent to list its available tools
Expected Behavior
The agent should have access to all tools provided by the pencil MCP server (e.g., get_editor_state, get_screenshot, batch_get, get_variables).
Actual Behavior
The agent reports zero MCP tools from the pencil server. Only the standard built-in tools (Bash, Glob, Grep, Read, Edit, Write, etc.) are available.
Additional Context
- The MCP server binary exists and starts correctly (
Starting server in stdio mode) - The permission
mcp__pencilis already allowed insettings.json - The MCP server is not configured globally (
~/.claude/mcp_settings.json) or at project level (.mcp.json) — it is only defined in the agent YAML - Possible that YAML-level
mcpServersonly work when the agent is invoked directly (e.g.,/agent frontend-implement) but not when spawned as a subagent through the Task tool
Environment
- macOS (Darwin 25.2.0, arm64)
- Claude Code CLI (Claude Opus 4.6)
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗