[BUG] Agent tools allowlist cannot reference plugin MCP tools

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Title: Agent tools allowlist cannot reference plugin MCP tools

Version: 2.1.126

Summary

When a plugin provides MCP tools via .mcp.json, agent definitions cannot restrict tool access using the tools: frontmatter array. The agent either gets no MCP tools (if tools is present) or all session tools (if tools is omitted). There's no way to scope an agent to a subset
of plugin MCP tools.

Plugin structure

acme-prototype/
├── .claude-plugin/plugin.json
├── .mcp.json # MCP server "acme-prototype"
├── settings.json
├── skills/prototype-search/SKILL.md
└── agents/prototype-orient.md

What works

• Plugin loads, MCP connects, tools are callable from the main session.
• Permission wildcard in settings.json works with the plugin: format:

{ "permissions": { "allow": ["plugin:acme-prototype:acme-prototype - *"] } }

• Skill allowed-tools works with the plugin: format:

allowed-tools: plugin:acme-prototype:acme-prototype - search

What doesn't work

Agent tools: array — tried both naming formats, neither gives the agent access to plugin MCP tools:

Attempt 1: mcp__ format — agent runs but "No such tool available: search"
tools: [mcp__acme-prototype__search, mcp__acme-prototype__read]

Attempt 2: plugin: format — same result
tools: ["plugin:acme-prototype:acme-prototype - search", "plugin:acme-prototype:acme-prototype - read"]

Workaround

Omit the tools array entirely. The agent inherits all session tools including plugin MCP tools. Behavioral scope is controlled by the agent prompt instead.

---
name: prototype-orient
model: sonnet
maxTurns: 15
skills:

• prototype-search

---

This works — the agent successfully calls plugin MCP tools. But it means agents can't be restricted to a subset of tools when working with plugins.

Expected behavior

The tools: array should accept the same plugin:<plugin>:<server> - <tool> format that works in settings.json permissions and skill allowed-tools.

Reproduction

1. Create a plugin with an MCP server in .mcp.json
2. Define an agent with tools: ["plugin:<plugin>:<server> - <tool>"]
3. Invoke the agent — it cannot access the listed MCP tools
4. Remove the tools array, invoke again — agent can access all MCP tools

Related: #38044 (controllable subagent context / MCP schema inheritance). That issue covers context overflow from too many inherited MCP tools. This issue is narrower: plugin MCP tools cannot be referenced in tools: at all, regardless of naming format.

What Should Happen?

Expected behavior

The tools: array should accept the same plugin:<plugin>:<server> - <tool> format that works in settings.json permissions and skill allowed-tools.

Error Messages/Logs

Steps to Reproduce

Reproduction

1. Create a plugin with an MCP server in .mcp.json
2. Define an agent with tools: ["plugin:<plugin>:<server> - <tool>"]
3. Invoke the agent — it cannot access the listed MCP tools
4. Remove the tools array, invoke again — agent can access all MCP tools

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.126

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_