claude-mcp-allow: least-privilege Claude Code permission rules for MCP tools
Generate permissions.allow and permissions.ask rules for every MCP tool Claude Code can reach, from the annotations each server reports on tools/list: a tool that says readOnlyHint: true (and not destructiveHint: true) gets an allow rule, everything else gets an ask rule, one exact mcp__<server>__<tool> rule per tool and never a glob. --write merges the rules into the settings file you choose, --diff shows what would change, and --check reconnects later and exits 1 when a server's annotations have drifted from the rules you saved.
It is for people who use Claude Code with MCP servers and want read-only tools to stop prompting without allowing everything, and for teams who commit .claude/settings.json and want CI to notice when a server's annotations change.
Quick start
No install and no token needed; run it from a project whose MCP servers you want rules for:
npx github:basitalisandhu/claude-mcp-allow # print the proposed rules, change nothing
npx github:basitalisandhu/claude-mcp-allow --diff --write
npx github:basitalisandhu/claude-mcp-allow --check # later, or in CI: exit 1 on drift
npx github: fetches the source from GitHub and builds it on first use (pin a release with #v0.4.0). For a server that marks its tools, the report looks like this:
annotated (project, .mcp.json) 7 tools: 2 allow, 5 ask
allow get_user readOnlyHint is true
allow list_items readOnlyHint is true
ask delete_item destructiveHint is true
ask update_item annotated but not marked read-only
The problem
Claude Code asks before every MCP tool call unless a permission rule covers it. Its permission engine does not read MCP tool annotations: the request to auto-allow readOnlyHint tools and keep prompting for destructiveHint ones (anthropics/claude-code#87452) was closed as not planned, and on Claude Code on the web the connector prompt offers only "Allow once", so read-only tools ask on every call and unattended runs stall (anthropics/claude-code#99112). The permissions docs give you the rule syntax (mcp__<server>, mcp__<server>__<tool>, and mcp__<server>__* only after a literal server prefix) and leave the rule writing to you. So people hand-roll hooks that guess by verb, or allow a whole server, or keep clicking.
This tool writes the rules for you, from what the servers themselves report, and tells you when that report changes.
Security model
Annotations are untrusted hints. The MCP project's own guidance on tool annotations is that every annotation property is a hint and clients must treat them as untrusted unless the server is trusted, and that many servers ship without them. This tool therefore never auto-allows a tool that is not marked read-only: without annotations a tool goes to ask, a tool with destructiveHint: true goes to ask even when it also claims readOnlyHint: true, and a tool whose tools/list entry carries _meta["anthropic/requiresUserInteraction"]: true goes to ask regardless, because Claude Code prompts for it on every call even when an allow rule matches. --heuristic is opt-in, allows only unannotated tools whose name starts with a read verb and a separator (get_, list-, search_ and so on), and is recorded in the file so --check applies the same judgement later. Every rule is one tool on one server; the tool never emits mcp__* or mcp__<server>__*, never touches deny rules or rules it did not write, and records the decision and a SHA-256 of each tool's annotations next to the rules, so --check can detect drift: an annotation that changed, a tool that disappeared, or an allowed tool that would no longer be allowed. Running the tool starts every configured stdio server with its configured command, environment and arguments, exactly as Claude Code would; review your configuration before running it against servers you do not trust.
Install
Requires Node 20 or newer.
The quickest route needs nothing but Node: npx github:basitalisandhu/claude-mcp-allow <options>, as in the Quick start. The container image below also works without any login.
Every release is published by publish-github-packages.yml in two places on GitHub Packages: the npm package @basitalisandhu/claude-mcp-allow and the container image ghcr.io/basitalisandhu/claude-mcp-allow. The package is not on npmjs.com yet; when it is, it will use the same scoped name.
npm from GitHub Packages
Point the @basitalisandhu scope at GitHub Packages in ~/.npmrc:
@basitalisandhu:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
GitHub's npm registry asks for a token even to install public packages. That is a GitHub limitation, not a setting of this repository: use a personal access token (classic) with the read:packages scope, exported as GITHUB_TOKEN. Then:
npx @basitalisandhu/claude-mcp-allow # run without installing
npm install -g @basitalisandhu/[email protected] # or install the claude-mcp-allow command
Container image
The image is built for linux/amd64 and linux/arm64, runs as the non-root node user (home /home/node), and is tagged with the version and latest; pin the version. The working directory is /work, so mount the project there:
docker run --rm -v "$PWD:/work" ghcr.io/basitalisandhu/claude-mcp-allow:0.4.0 --diff
The container sees only what you mount. To include user-scope servers, also mount ~/.claude.json at /home/node/.claude.json. Stdio servers are started inside the container, so only servers whose command exists in the image (Node.js is available) can be reached; HTTP servers work as long as the container can reach them. For anything else, run the npm package on the host.
The image is signed with cosign (keyless) and carries a build provenance attestation; an SPDX SBOM is attached to the GitHub release. To check it before running it:
cosign verify ghcr.io/basitalisandhu/claude-mcp-allow:0.4.0 \
--certificate-identity-regexp '^https://github.com/basitalisandhu/claude-mcp-allow/\.github/workflows/publish-github-packages\.yml@refs/tags/v' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
gh attestation verify oci://ghcr.io/basitalisandhu/claude-mcp-allow:0.4.0 --owner basitalisandhu
To build the image from a checkout: docker build -t claude-mcp-allow .
From a clone
git clone https://github.com/basitalisandhu/claude-mcp-allow && cd claude-mcp-allow
npm install && npm run build
node dist/cli.js --help
Usage
claude-mcp-allow [--cwd dir] [--scope local|project|user] [--heuristic] [--write] [--diff] [--prune] [--check] [--server name] [--timeout ms] [--managed-dir dir]
| Flag | What it does |
|---|
--cwd <dir> | The project directory. Defaults to the current directory. .mcp.json, .claude/settings.json and the projects[<dir>] entry of ~/.claude.json are read relative to it. |
--scope local|project|user | Which settings file --write, --diff and --check use: .claude/settings.local.json (default; at the git repository root when the directory is inside one, as Claude Code does), .claude/settings.json, or ~/.claude/settings.json. |
--heuristic | Also allow unannotated tools whose name matches ^(get|list|read|search|find|fetch|describe|show|query|count|lookup)[_-]. Annotated tools are never affected. |
--write | Merge the proposed rules into the settings file for --scope. Existing keys, key order, indentation and every rule the tool did not write are preserved. |
--diff | Print the rules --write would add and remove, as + allow, + ask, - allow and - ask lines. Combine with --write to see and apply in one run. |
--prune | With --write or --diff, remove only marker-recorded rules and marker entries for servers absent from the current project's configuration. Off by default. With user scope, this can remove generated rules for other projects: inspect --diff --prune first. Configured but filtered, disabled or unavailable servers are preserved; incomplete configuration loading refuses pruning. |
--check | Reconnect to every server recorded in the settings file, recompute the annotation hashes, and exit 1 on drift. Requires a file written by --write. |
--server <name> | Only this server. Repeatable. Matches the configured name, plugin:<plugin>:<server> for plugin servers, or the server segment of the rule. |
--timeout <ms> | Per-server limit for connecting and for tools/list. Default 20000. |
--managed-dir <dir> | Read and from instead of the platform policy directory, so an administrator can preview a policy before deploying it. See . |
Exit codes: 0 success, 1 drift found by --check, 2 usage or configuration error (an unknown flag, a settings file that is not valid JSON, --check without a marker).
The proposed permissions block is printed on stdout as JSON; the per-server report, warnings and the wrote line go to stderr, so claude-mcp-allow > rules.json captures only the block.
Where servers are read from
The tool reads the same places Claude Code does, in the documented precedence, and tells you where each server came from. When one name is defined in several places, the highest-precedence definition wins and the others are reported as shadowed. Plugin servers are matched against the others by endpoint (URL or command), as the docs describe.
| Precedence | Source | File |
|---|
| 0 | organisation-managed | managed-mcp.json and managedMcpServers in managed-settings.json at the platform policy path |
| 1 | local scope | ~/.claude.json, projects["<cwd>"].mcpServers |
| 2 | project scope | <cwd>/.mcp.json |
| 3 | user scope | ~/.claude.json, top-level mcpServers |
| 4 | enabled plugins | .mcp.json at each plugin root and mcpServers in its .claude-plugin/plugin.json, found through ~/.claude/plugins/installed_plugins.json and enabledPlugins in your settings files |
Organisation-managed servers are reported with origin managed; the rules for them are under Organisation-managed servers. Connectors fetched from claude.ai are not read. CLAUDE_CONFIG_DIR moves ~/.claude (settings and plugins; .claude.json is read from there when it exists) and CLAUDE_CODE_PLUGIN_CACHE_DIR moves the plugins root. Servers listed in disabledMcpjsonServers or disabledMcpServers are skipped. A server that matches a deniedMcpServers entry from user, project, local or managed settings is skipped as blocked by deniedMcpServers: entries match a server by name, by command and arguments (exact, in order), or by a serverUrl without *. Wildcard serverUrl entries are not evaluated yet and each one is named in a warning. ${VAR} and ${VAR:-default} are expanded in command, args, env, url and headers; an unset variable without a default is left as written with a warning, and the credential variables Claude Code reads as empty in a remote server's url and headers (such as ANTHROPIC_API_KEY and NPM_TOKEN) are read as empty here too. ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA} and ${CLAUDE_PROJECT_DIR} are expanded for plugin servers.
Organisation-managed servers
Claude Code has two ways for an organisation to provide MCP servers, and this tool applies the documented rules for both:
managed-mcp.json has exclusive control. When the file exists and parses, only its servers and the managedMcpServers entries load; servers from .mcp.json, ~/.claude.json and plugins are reported as skipped. Its entries may use command, args, env and ${VAR} like any .mcp.json.managedMcpServers in managed-settings.json adds remote servers alongside the user's own. An entry is refused, with the reason in a warning, unless its type is http, sse or streamable-http, its url is https://, it has no command, args, env or headersHelper, it uses no ${VAR} reference, its name uses only letters, numbers, hyphens and underscores, and no key or value contains a control or invisible formatting character. The array form used by Claude Desktop's setting of the same name is ignored with a warning.- When both define the same name, the
managed-mcp.json entry wins and the other is reported as shadowed. A managed server takes precedence over a local, project or user server of the same name, and a user can still turn one off with disabledMcpServers.
The files are read from /Library/Application Support/ClaudeCode on macOS, /etc/claude-code on Linux and WSL, and C:\Program Files\ClaudeCode on Windows. To try a policy before it reaches anyone's machine, put the two files in a folder and pass --managed-dir. With this policy:
// policy/managed-mcp.json
{ "mcpServers": { "annotated": { "command": "node", "args": ["<clone>/tests/fixtures/annotated-server.mjs"] } } }
// policy/managed-settings.json
{
"managedMcpServers": {
"annotated": { "type": "http", "url": "https://mcp.example.com/annotated" },
"intranet": { "type": "http", "url": "http://intranet.example.com/mcp" },
"tenant": { "type": "http", "url": "https://${TENANT}.example.com/mcp" }
}
}
a project whose .mcp.json defines the unannotated fixture gives this report on stderr (absolute paths shortened to /demo):
$ claude-mcp-allow --managed-dir ../policy
note: annotated from /demo/policy/managed-settings.json is shadowed by the managed definition (/demo/policy/managed-mcp.json)
warning: intranet (managed, /demo/policy/managed-settings.json) skipped: managedMcpServers entries must define an HTTPS URL
warning: tenant (managed, /demo/policy/managed-settings.json) skipped: managedMcpServers entries must use literal values without ${VAR} references
warning: unannotated (project, .mcp.json) skipped: managed-mcp.json has exclusive control
annotated (managed, /demo/policy/managed-mcp.json) 7 tools: 2 allow, 5 ask
allow get_user readOnlyHint is true
allow list_items readOnlyHint is true
ask delete_item destructiveHint is true
ask update_item annotated but not marked read-only
ask read_and_wipe destructiveHint is true (readOnlyHint is also true; the destructive hint wins)
ask grant_access _meta["anthropic/requiresUserInteraction"] is true; Claude Code prompts on every call
ask get_status no annotations
The rules on stdout are then the two allow and five ask rules for annotated only. allowedMcpServers is not evaluated; a deniedMcpServers match would skip the server.
Tools from a plugin-bundled server get rules in the form Claude Code uses for them, mcp__plugin_<plugin>_<server>__<tool>, with any character outside A-Z, a-z, 0-9, _ and - replaced by _.
What is skipped, and why
- Entries with an
oauth key, and remote servers that answer 401 or 403: Claude Code completes the sign-in through /mcp; this tool does not run OAuth flows. Each one is named in a warning.
ws and sdk transports, and entries with neither command nor url.- Plugin entries that reference
${user_config.*}, which this tool does not resolve.
- Servers that match a
deniedMcpServers entry by name, by command and arguments, or by a URL without *; a serverUrl entry containing * is not evaluated yet and is named in a warning.
- A server that fails to start or does not answer within
--timeout is reported as failed, and the rest continue.
What --write puts in the file
Rules are appended to permissions.allow and permissions.ask, and a sibling key records what was generated:
"claudeMcpAllow": {
"generatedBy": "claude-mcp-allow 0.4.0",
"generatedAt": "2026-10-03T22:38:08.944Z",
"heuristic": false,
"servers": {
"annotated": {
"get_user": "allow:cd6fc3f14d1a476831d8b3ad5283d55120abdc84f8fdff6a2b040e092f81afcc",
"delete_item": "ask:8c2fe572a84b307ba8332b68b40a6b8ccb02f58b7b81e61943e7ac03862756fd"
}
}
}
Each value is the decision and the SHA-256 of the tool's annotations plus its requiresUserInteraction flag (the description and schema are not hashed, so wording changes do not count as drift). On the next --write, rules recorded here are replaced by the new result; rules you wrote by hand stay, and the tool warns when a hand-written allow covers a tool it classified ask (the ask rule is evaluated first and prompts). An allow rule for a tool that appears in permissions.deny is not added, because deny rules win. The published settings schema accepts additional top-level keys, so the marker does not make the file invalid.
--check reads this key, reconnects to each recorded server (or the ones you name with --server) and reports drift when a hash differs, a tool is no longer listed, an allowed tool would not be allowed now, a recorded server is no longer configured, or a server cannot be reached; it reports info for new tools that are not covered yet and for hand-written allow rules on ask tools. Exit 1 on any drift.
Sample output
A project with two fixture servers from this repository in .mcp.json (one annotated, one not) and a user-scope server that needs OAuth, from npx @basitalisandhu/claude-mcp-allow with no flags:
annotated (project, .mcp.json) 7 tools: 2 allow, 5 ask
allow get_user readOnlyHint is true
allow list_items readOnlyHint is true
ask delete_item destructiveHint is true
ask update_item annotated but not marked read-only
ask read_and_wipe destructiveHint is true (readOnlyHint is also true; the destructive hint wins)
ask grant_access _meta["anthropic/requiresUserInteraction"] is true; Claude Code prompts on every call
ask get_status no annotations
unannotated (project, .mcp.json) 15 tools: 0 allow, 15 ask
ask get_weather no annotations
ask list_files no annotations
ask search_docs no annotations
ask fetch-url no annotations
ask lookup_user no annotations
ask count_rows no annotations
ask show-status no annotations
ask query_db no annotations
ask getdata no annotations
ask send_email no annotations
ask delete_all no annotations
ask update_record no annotations
ask run_job no annotations
ask get_consent _meta["anthropic/requiresUserInteraction"] is true; Claude Code prompts on every call
ask get_string_flag no annotations
docs (user, ~/.claude.json) skipped: entry has oauth; sign in with /mcp in Claude Code, this tool does not run OAuth flows
{
"permissions": {
"allow": [
"mcp__annotated__get_user",
"mcp__annotated__list_items"
],
"ask": [
"mcp__annotated__delete_item",
"mcp__annotated__get_status",
"mcp__annotated__grant_access",
"mcp__annotated__read_and_wipe",
"mcp__annotated__update_item",
"mcp__unannotated__count_rows",
"mcp__unannotated__delete_all",
"mcp__unannotated__fetch-url",
"mcp__unannotated__get_consent",
"mcp__unannotated__get_string_flag",
"mcp__unannotated__get_weather",
"mcp__unannotated__getdata",
"mcp__unannotated__list_files",
"mcp__unannotated__lookup_user",
"mcp__unannotated__query_db",
"mcp__unannotated__run_job",
"mcp__unannotated__search_docs",
"mcp__unannotated__send_email",
"mcp__unannotated__show-status",
"mcp__unannotated__update_record"
]
}
}
With --heuristic --server unannotated, read verbs with a separator are allowed; getdata has no separator, send_email is not a read verb, and get_consent requires a person:
unannotated (project, .mcp.json) 15 tools: 9 allow, 6 ask
allow get_weather no annotations; name starts with a read verb (--heuristic)
allow list_files no annotations; name starts with a read verb (--heuristic)
allow search_docs no annotations; name starts with a read verb (--heuristic)
allow fetch-url no annotations; name starts with a read verb (--heuristic)
allow lookup_user no annotations; name starts with a read verb (--heuristic)
allow count_rows no annotations; name starts with a read verb (--heuristic)
allow show-status no annotations; name starts with a read verb (--heuristic)
allow query_db no annotations; name starts with a read verb (--heuristic)
ask getdata no annotations; name is not a read verb
ask send_email no annotations; name is not a read verb
ask delete_all no annotations; name is not a read verb
ask update_record no annotations; name is not a read verb
ask run_job no annotations; name is not a read verb
ask get_consent _meta["anthropic/requiresUserInteraction"] is true; Claude Code prompts on every call
allow get_string_flag no annotations; name starts with a read verb (--heuristic)
--write --diff against a .claude/settings.local.json that already allowed Bash(npm test) (the proposed block is printed first and is omitted here):
Diff against .claude/settings.local.json:
+ allow mcp__annotated__get_user
+ allow mcp__annotated__list_items
+ ask mcp__annotated__delete_item
+ ask mcp__annotated__get_status
+ ask mcp__annotated__grant_access
+ ask mcp__annotated__read_and_wipe
+ ask mcp__annotated__update_item
+ ask mcp__unannotated__count_rows
...
+ ask mcp__unannotated__update_record
wrote .claude/settings.local.json: +2/-0 allow, +20/-0 ask
The file afterwards starts with the rule that was already there:
{
"permissions": {
"allow": [
"Bash(npm test)",
"mcp__annotated__get_user",
"mcp__annotated__list_items"
],
"ask": [
"mcp__annotated__delete_item",
--check straight away, then again after the annotated server was changed to report readOnlyHint: false for get_user (the fixture does this when FIXTURE_DRIFT=flip is set):
$ npx @basitalisandhu/claude-mcp-allow --check
ok: no drift against .claude/settings.local.json
$ FIXTURE_DRIFT=flip npx @basitalisandhu/claude-mcp-allow --check
drift annotated: annotations of get_user changed; it is allowed but is no longer read-only (annotated but not marked read-only)
1 drift finding(s) against .claude/settings.local.json
The second run exits 1, which is what you want from a CI job or a pre-commit hook that guards a committed .claude/settings.json.
Troubleshooting
Each message below is real output. Configuration and usage errors exit with code 2; drift found by --check exits with code 1.
| You see | What it means | Fix |
|---|
npm error code E401 from npx @basitalisandhu/claude-mcp-allow | GitHub Packages asks for a token even for public packages. | Use npx github:basitalisandhu/claude-mcp-allow, which needs none, or the container image. |
claude-mcp-allow: no MCP servers configured for <dir> | No .mcp.json, ~/.claude.json entry, plugin or managed server applies to that directory. | Run it from the project root or pass --cwd <dir>; see Where servers are read from. |
warning: <dir>/.mcp.json: invalid JSON (...); ignored | The file has a trailing comma, a comment or a cut-off end. | Fix the JSON; Claude Code would not load those servers either. |
x (project, .mcp.json) failed: spawn no-such-cmd-zz ENOENT | The server's command is not on your PATH. | Install the server, or use the full path in command. Its tools get no rules until it lists them. |
A server shows failed: ... timed out | It did not answer tools/list within --timeout (20 seconds by default). | Start it once by hand to see why, or raise --timeout. |
claude-mcp-allow: .claude/settings.local.json has no claudeMcpAllow marker; run claude-mcp-allow --write first | --check compares with rules this tool wrote; there are none in that file. | Run --write with the same --scope first. |
claude-mcp-allow: --scope must be local, project or user (got "team") | Only the three settings files are written. | Pick one; local is the default and is not committed. |
--check reports drift right after a server upgrade | The server changed an annotation, removed a tool, or an allowed tool is no longer read-only. | Review the change, then run --write again to record it. |
Frequently asked questions
Why does Claude Code still prompt for a tool that has an allow rule?
Four documented reasons. A tool whose tools/list entry sets _meta["anthropic/requiresUserInteraction"] to true prompts on every call, in every mode, and allow rules do not skip it; this tool puts such tools in ask so the file matches the behaviour. Rules are evaluated deny, then ask, then allow, first match wins, so an ask rule from any settings file (yours, the project's, or your organisation's) prompts even when a more specific allow rule also matches. permissions.allow rules in a project's .claude/settings.json only apply after you accept the workspace trust dialog for that folder. And when your organisation has set a claude.ai connector tool to ask, allow rules for that tool do not take effect. Run /permissions in Claude Code to see every rule and the file it comes from.
Can I trust readOnlyHint?
Only as far as you trust the server. Annotations are declared by the server and nothing checks them; a server can call a tool read-only and still write. That is why the default never allows a tool that is not marked read-only, why --heuristic is a separate choice, and why --check exists: once you have reviewed and saved the rules, a server that later changes a tool's annotations, drops a tool, or starts claiming something different fails the check instead of silently widening what runs without a prompt. Treat the generated allow list the way you would treat a dependency lockfile: review it when it changes.
Why one rule per tool instead of mcp__<server>__*?
The wildcard form is valid and Claude Code accepts it after a literal server prefix, but it allows every tool the server has now and every tool it adds later, including a destructive one shipped in a future version. One exact rule per tool keeps the allowlist readable in review, lets --diff show exactly which capability a change adds, and lets --check reason about each tool's own annotations. Unanchored globs such as mcp__* are skipped by Claude Code with a warning and never auto-approve anything, so the tool never writes them either.
Which settings file should the rules go in, and can I commit it?
local (the default) writes .claude/settings.local.json, your personal file for this project, which Claude Code keeps out of git when it creates the file; if you created it by hand, add it to .gitignore yourself. project writes .claude/settings.json, which you commit so teammates get the same rules, and which is the file to guard with --check in CI. user writes ~/.claude/settings.json, which applies to every project on your machine; rules for project-scoped servers rarely belong there. Whatever the file, a deny rule from any settings file still wins over an allow rule from another.
Development
npm install
npm test # builds, then runs vitest against the fixture servers in a temporary home directory
npm run typecheck
The suite starts the two stdio fixtures (tests/fixtures/annotated-server.mjs, tests/fixtures/unannotated-server.mjs) and a Streamable HTTP fixture that requires a bearer token, inside a fake home directory with servers in every scope, and compares output against the golden files in tests/golden/. Regenerate the goldens with UPDATE_GOLDEN=1 npm test and review the diff. See CONTRIBUTING.md, docs/good-first-issues.md and SECURITY.md.
Sibling projects
More tools by the same author: https://github.com/basitalisandhu
- agent-security-skills: Claude Code plugin and agentskills-compatible skill pack for agent security reviews.
- mcp-tools-lint: lint an MCP server's
tools/list for schema dialect, annotation and naming problems before a client rejects it.
- agent-threat-model: threat modeling for AI agents from a YAML description.
Licence
MIT, see LICENSE. Copyright 2026 Muhammad Basit Ali.
