Skip to content

docs: clarify plugin MCP tool permissions #1141

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yaodong-shen wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify plugin MCP tool permissions #1141

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
9 changes: 7 additions & 2 deletions src/claude_agent_sdk/types.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down Expand Up @@ -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
Expand Down