Subagent tools field does not support MCP wildcards or server-prefix shortcuts (re-opens #17928)

Summary

The subagent tools: frontmatter field does not accept MCP wildcards (mcp__<server>__*) or server-prefix shortcuts (mcp__<server>). Both forms show ⚠ Unrecognized in the /agents dialog and the MCP tools are not available to the subagent. Only exact tool names work.

This affects both directly-registered MCP servers (in project .mcp.json) and plugin-provided MCP servers (with mcp__plugin_<plugin>_<server>__* namespace). We reproduced both cases.

This is a continuation of #17928, which was auto-closed as stale without resolution.

Environment

• Claude Code version: 2.1.119
• Platform: Linux

Reproduction

Setup — directly-registered MCP (non-plugin)

.mcp.json at project root:

{
  "mcpServers": {
    "codemaps-direct": {
      "command": "sh",
      "args": ["-c", "docker run ... codemaps-mcp-image"]
    }
  }
}

Subagent at .claude/agents/codemaps-test.md (also outside any plugin):

---
name: codemaps-test
tools: mcp__codemaps-direct__*, Read
---

Observed: /agents shows ⚠ Unrecognized: mcp__codemaps-direct__*

Setup — plugin-provided MCP

Plugin's .mcp.json:

{
  "mcpServers": {
    "datadog": {
      "type": "http",
      "url": "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp"
    }
  }
}

Subagent in the plugin:

tools: mcp__plugin_observability_datadog__*, Read

Observed: /agents shows ⚠ Unrecognized: mcp__plugin_observability_datadog__*

What we tested (all fail with Unrecognized or server-not-connected)

Tested with session restarts after each change:

1. tools: mcp__<server>__* (wildcard) — Unrecognized (both plugin and non-plugin)
2. tools: mcp__<server> (prefix-only, per permission docs) — Unrecognized
3. mcpServers: [<server-name>] in subagent frontmatter — server not connected
4. mcpServers: { <server-name>: {} } — server not connected
5. mcpServers: with inline HTTP definition — server not connected
6. allowed-tools: field (slash-command syntax) — silently ignored, agent inherits all tools

The only working pattern is explicit enumeration of every tool name.

Impact

Plugin and subagent authors who want to scope a subagent to a specific MCP server must either:

• (a) Enumerate every tool explicitly (high maintenance — breaks every time the server adds/renames a tool)
• (b) Omit tools: entirely and inherit all parent-session tools (loses scoping)

We found 24+ public repos using the broken wildcard pattern in published plugins (see e.g. opentrace/claude-code, gprecious/ultrawork-plugin, hrconsultnj/claude-plugins/plugins/composure). Authors appear to believe it works; no warning or error is surfaced beyond the /agents dialog.

Documentation conflict

• Permission rule syntax documents mcp__<server>__* and mcp__<server> as valid — but only for permissions.allow, not for subagent tools:.
• Subagent docs don't clarify this distinction. The mcpServers: field documented there also doesn't resolve plugin-provided servers (tested above).

Ask

• Support wildcards and server-prefix forms in subagent tools: to match the permission system, OR
• Document clearly that tools: requires exact MCP tool names and that mcpServers: is the only way to scope MCP access (and make mcpServers: actually work for plugin-provided servers).