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

  1. Create an agent definition at .claude/agents/frontend-implement.md with 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
---
  1. Spawn the agent via the Task tool (as a subagent)
  2. 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__pencil is already allowed in settings.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 mcpServers only 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)

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗