From e67981b27b9dc709b41d44c374c4081986be7d6e Mon Sep 17 00:00:00 2001
From: yaodong-shen <yaodong-shen@users.noreply.github.com>
Date: Tue, 21 Jul 2026 20:19:59 +0800
Subject: [PATCH] docs: clarify plugin MCP tool permissions

---
 README.md                     | 28 ++++++++++++++++++++++++++++
 src/claude_agent_sdk/types.py |  9 +++++++--
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 8d8445238..390cea07e 100644
--- a/README.md
+++ b/README.md
@@ -184,6 +184,34 @@ options = ClaudeAgentOptions(
 )
 ```
 
+#### Plugin MCP Server Permissions
+
+MCP servers bundled with an enabled plugin start automatically, but starting a
+server does not grant permission to call its tools. Plugin MCP tools use the
+same permission flow as other MCP tools and follow the
+`mcp__<server-name>__<tool-name>` naming pattern.
+
+- Add a tool to `allowed_tools` to approve it without prompting.
+- Leave it out of `allowed_tools` to let `permission_mode`, permission rules,
+  and `can_use_tool` decide whether the call is allowed.
+- Use `disallowed_tools` to block a tool. `PreToolUse` hooks can observe or gate
+  plugin MCP calls just like other tool calls.
+
+For example, this configuration auto-approves one tool while keeping other
+tools from the same plugin on the normal permission path:
+
+```python
+options = ClaudeAgentOptions(
+    plugins=[{"type": "local", "path": "/path/to/plugin"}],
+    permission_mode="default",
+    allowed_tools=["mcp__plugin-server__read_data"],
+)
+```
+
+Permission checks apply when a tool is called; they do not sandbox the plugin's
+MCP server process. Because an enabled plugin can start that process and pass it
+environment variables, only load plugins you trust.
+
 ### Hooks
 
 A **hook** is a Python function that the Claude Code _application_ (_not_ Claude) invokes at specific points of the Claude agent loop. Hooks can provide deterministic processing and automated feedback for Claude. Read more in [Intercept and control agent behavior with hooks](https://platform.claude.com/docs/en/agent-sdk/hooks).
diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py
index 5b7926449..98a933c35 100644
--- a/src/claude_agent_sdk/types.py
+++ b/src/claude_agent_sdk/types.py
@@ -826,6 +826,9 @@ class SdkPluginConfig(TypedDict):
     """SDK plugin configuration.
 
     Currently only local plugins are supported via the 'local' type.
+    MCP servers bundled with an enabled plugin start automatically, but their
+    tools still follow the standard MCP permission flow. Loading a plugin does
+    not auto-approve its tools.
     """
 
     type: Literal["local"]
@@ -1997,8 +2000,10 @@ class ClaudeAgentOptions:
     plugins: list[SdkPluginConfig] = field(default_factory=list)
     """Load plugins for this session.
 
-    Plugins provide custom commands, agents, skills, and hooks that extend
-    Claude Code's capabilities. Currently only local plugins are supported.
+    Plugins provide custom commands, agents, skills, hooks, and MCP servers that
+    extend Claude Code's capabilities. Currently only local plugins are
+    supported. Plugin MCP tools do not bypass ``allowed_tools``,
+    ``disallowed_tools``, ``permission_mode``, ``can_use_tool``, or hooks.
     """
 
     max_thinking_tokens: int | None = None