In Claude Code, how is a connected MCP server's tool named, and how do you write permission rules for one tool or a whole server?
answer
- double underscores, three segments
- server name as you configured it
- bare server rule covers every tool
- allow globs need a literal server prefix
- no parentheses on mcp__ rules in settings
basics
~20 sClaude Code names each MCP tool mcp__<server><tool>, using the server name from your configuration. The rule mcp__server or mcp__server* covers every tool on that server, mcp__server__tool covers one, and an allow glob must start with a literal server prefix.
solid answer
~40 sEvery tool from a connected server is exposed as `mcp__<server>__<tool>`, where `<server>` is the name you gave the server in your configuration, so `mcp__tracker__get_issue` is the `get_issue` tool of the server you called `tracker`. Permission rules use the same names: `mcp__tracker` and `mcp__tracker__*` both cover every tool on that server, and `mcp__tracker__get_issue` covers one. Deny and ask rules accept a glob anywhere in the name, so `mcp__*` in `permissions.deny` removes every MCP tool, but an allow glob only counts after a literal `mcp__<server>__` prefix: an allow rule of `mcp__*` is skipped with a warning and approves nothing. Settings files also skip any `mcp__` rule written with parentheses; parameter matching on an MCP tool works only as a deny rule passed with `--disallowedTools`.
code
json · 7 lines{
"permissions": {
"allow": ["mcp__tracker__get_*", "mcp__docs"],
"ask": ["mcp__tracker__delete_issue"],
"deny": ["mcp__scratch"]
}
}go deeper
Recall the three-part name, mcp__ then the server name you configured then the tool name, and find it in the /mcp panel before you write any rule.
Explain the rule forms: bare server, server plus wildcard, single tool, and why an allow glob must keep a literal server prefix while deny and ask may glob freely.
Show you can lock a many-server session down: prefix allows for read tools, ask for destructive ones, deny for idle servers, and know which tools still prompt regardless.
Weigh broad server-level allows against per-tool rules when repositories add servers through shared config, and decide where a deny-all baseline beats curating allows.
## How Claude Code names MCP tools An **MCP server** is an external program that offers tools to Claude Code. Claude Code does not show those tools under the names the server uses internally; it prefixes each one so tools from different servers don't collide with each other or with built-in tools such as `Bash` or `Edit`. The pattern is: - `mcp__<server>__<tool>`, with **double underscores** between the three segments - `<server>` is the **name you configured** for the server, not a name the server announces about itself - `<tool>` is the tool's own name as the server lists it So a server you added under the name `tracker` that offers `get_issue` and `delete_issue` gives Claude `mcp__tracker__get_issue` and `mcp__tracker__delete_issue`. The `/mcp` panel shows each connected server with its tool count, which is where you check the exact names before writing rules. Two variations matter in practice. Tools from a **claude.ai connector** that Claude Code fetches itself appear as `mcp__claude_ai_<server>__<tool>`. Tools from a server bundled inside a plugin carry the plugin name as well (`mcp__plugin_<plugin>_<server>__<tool>`), so a rule written against the bare server key never matches them; packaging is the plugins material's subject, but the naming consequence lands here. ## Writing permission rules on MCP tools Permission rules live in `permissions.allow`, `permissions.ask` and `permissions.deny`. For MCP tools the specifier is the name itself: | Rule | What it covers | | :- | :- | | `mcp__tracker` | every tool from the `tracker` server | | `mcp__tracker__*` | every tool from the `tracker` server (wildcard form) | | `mcp__tracker__get_*` | the `tracker` tools whose names start with `get_` | | `mcp__tracker__get_issue` | that one tool | | `mcp__*` (deny or ask only) | every MCP tool on every server | The general evaluation order (deny, then ask, then allow) and the rest of the rule grammar belong to the permission-rules material; what is specific to MCP is which globs count where. ## Globs: what allow accepts and what it skips 1. **Deny and ask** rules may put a glob anywhere in the tool name, as long as the pattern matches the full name. `mcp__*` in `permissions.deny` removes every MCP tool from Claude's context. 2. **Allow** rules accept a glob only after a literal `mcp__<server>__` prefix, and the server segment must be glob-free. `mcp__tracker__*` is fine; `mcp__*`, `*` or `mcp__*__read` as an allow rule is **skipped with a warning and approves nothing**. The asymmetry is deliberate. An allow rule should name a specific server you configured, because a broad allow would silently approve tools from any server added later, including one a project's `.mcp.json` brings in. ## Parameter matching and other traps - Built-in tools accept parameter rules such as `Agent(model:opus)` in deny and ask. For an MCP tool, **a settings file skips any `mcp__` rule that has parentheses** and lists it in the invalid-settings dialog at startup. To deny an MCP tool call by parameter value, pass the rule to `--disallowedTools` on the command line. - **Hook matchers are not permission rules.** A hook matcher of `mcp__tracker` is compared as an exact string and matches no tool; a hook needs `mcp__tracker__.*`. The same text means "the whole server" in a permission rule and "nothing" in a matcher. - Rules use the canonical name, not the label shown in the transcript. ## Approvals no rule can pre-empt Allow rules do not cover everything. A server can flag a tool with `_meta["anthropic/requiresUserInteraction"]` set to `true`; Claude Code then prompts on every call, even in `acceptEdits`, `auto` and `bypassPermissions`, offers no "don't ask again" option, ignores matching allow rules, and in `dontAsk` mode denies the call. A claude.ai connector tool that your organization set to `ask` behaves the same way when that setting reaches your session. ## A pattern for a session with many servers - Allow the read-only families you trust by prefix (`mcp__tracker__get_*`, `mcp__docs`). - Put destructive tools in `ask` by full name (`mcp__tracker__delete_issue`). - Deny a server you keep connected but never want Claude to call, or deny `mcp__*` in a locked-down run. - Check every name against `/mcp` before committing the rules, because a typo in an allow rule fails silently: it simply never matches. ## Why typos in MCP rules slip through Claude Code warns at startup when a deny or ask rule names a tool it doesn't know, to catch typos. Tool names containing `_` or `*` are **exempt from that check**, and every MCP name contains `_`. So a misspelled `mcp__trackr__delete_issue` in `permissions.deny` raises no warning and denies nothing. Treat MCP rules like code: copy names from `/mcp`, and test a deny by asking Claude to call the tool once.
- Why does Claude Code skip an allow rule of mcp__* but honour the same pattern as a deny rule?An allow glob must sit after a literal `mcp__<server>__` prefix so it names a server you configured. A bare `mcp__*` allow would auto-approve tools from any server that connects later, including one a repository's `.mcp.json` adds, so Claude Code skips it with a warning. Denying everything carries no such risk, so `mcp__*` works in `permissions.deny` and removes every MCP tool from context.
- You allowed mcp__tracker, yet one tracker tool still prompts on every call, even in auto mode. Why?The server has marked that tool with `_meta["anthropic/requiresUserInteraction"]: true`. Claude Code then shows its prompt on every call in every mode, ignores matching allow rules and offers no "don't ask again" option; in `dontAsk` mode it denies the call. A claude.ai connector tool your organization set to `ask` behaves the same way.
- How do you deny an MCP tool only when one of its arguments has a particular value?Not in a settings file: Claude Code skips any `mcp__` rule with parentheses there and reports it as invalid at startup. Pass the parameter rule as a deny rule with `--disallowedTools`, for example `mcp__db__run_query(database:prod)`, which matches calls where that top-level parameter equals `prod` exactly.
- MCP tools keep the bare names the server gives them
- An allow rule of mcp__* approves every MCP tool
- mcp__server only matches a tool literally named after the server
- A settings rule like mcp__db__query(database:prod) gates by parameter
- An allow rule always skips the prompt for any MCP tool
- The server segment is the name the server announces, not your configured name