Claude Agent SDK Security Guide: Permissions, Hooks, Sandboxing and MCP Done Safely

The Claude Agent SDK hands your application the same tools, agent loop and permission engine that power Claude Code, which means a few lines of configuration decide whether your agent can read a directory or run any shell command on the host. This guide explains how the SDK evaluates permissions, how hooks and the canUseTool callback fit together, how to isolate the agent process and keep credentials outside it, how MCP servers are authorised, and what to log. It is for engineers and security reviewers building custom agents. The interactive CLI is covered in the Claude Code Security Guide; this page covers the SDK as a library inside your own services. The SDK moves quickly and several behaviours are tied to specific Claude Code versions.

This is an independent guide from NHI Mgmt Group, based on Anthropic's public documentation as of November 2026. It is not sponsored or reviewed by Anthropic. Product features change, so confirm settings against Anthropic's current documentation.

Key takeaways

• Permissions run in a fixed six-step order. Hooks, then deny rules, then ask rules, then the permission mode, then allow rules, then your canUseTool callback; a deny rule wins even in bypassPermissions mode.
• allowed_tools is not an allowlist. It pre-approves the tools you name; unlisted tools still exist, and under bypassPermissions they are approved too. Use disallowed_tools or dontAsk to close the surface.
• Put mandatory checks in a PreToolUse hook. Calls approved by a mode or allow rule never reach canUseTool, but hooks run before every other step and a hook deny holds in every mode.
• The agent should never hold the keys. Anthropic recommends a proxy outside the agent's boundary that injects credentials, enforces a domain allowlist and logs requests.
• Default options are not multi-tenant safe. Omitting settingSources loads user, project and local settings, CLAUDE.md files, hooks and .mcp.json; isolate tenants with settingSources: [], per-tenant directories and disabled auto memory.

How identity and access work in the Claude Agent SDK

The SDK spawns and supervises a claude CLI subprocess, talking to it over stdio. That subprocess owns a shell, a working directory and JSONL session transcripts on local disk, and it acts with the operating system identity of whatever process launched it. There is no separate agent identity inside the SDK: the agent's effective access is the union of the host account's file and network access, the credentials in its environment, and whatever the permission engine approves. Treat each agent deployment as a non-human identity with its own runtime account, its own API key and its own scoped tool credentials.

Authentication to the model

• Claude API: the subprocess reads ANTHROPIC_API_KEY from its environment. The SDK does not load .env files automatically, so the key is wherever your process manager or secret store puts it.
• Cloud providers: set CLAUDE_CODE_USE_BEDROCK=1 (Amazon Bedrock), CLAUDE_CODE_USE_VERTEX=1 (Google Cloud), CLAUDE_CODE_USE_FOUNDRY=1 (Microsoft Foundry) or CLAUDE_CODE_USE_ANTHROPIC_AWS=1 with ANTHROPIC_AWS_WORKSPACE_ID, and the provider's own credential chain applies. That moves the identity question into your cloud IAM.
• Proxying: ANTHROPIC_BASE_URL sends sampling requests to a proxy you run, which can inject the key so it never sits in the agent's environment.
• Consumer login: Anthropic states that, unless previously approved, third-party developers may not offer claude.ai login or rate limits in products built on the SDK. Production agents authenticate with API keys or a cloud provider.

Key handling for the Claude API itself is covered in the Anthropic API Keys Security Guide.

The permission evaluation order

Every tool request passes through the same sequence. Knowing it is the single most useful piece of SDK security knowledge, because most misconfigurations come from assuming a later step can override an earlier one.

Some actions are never auto-approved by an allow rule: recognised critical-path removals with rm or rmdir (such as removing the home directory), Bash commands flagged as a dangerous rm, and reads from network paths. Anthropic notes the critical-path check can miss some commands, so it is a backstop, not a control you design around.

Admin roles and privileged access

The SDK has no admin console of its own. Privilege is expressed through the permission mode, the tool surface and who can change configuration files the agent loads. Choose the mode deliberately for each agent.

• Mode changes at runtime: set_permission_mode() (Python) and setPermissionMode() (TypeScript) change the mode mid-session. Any code path that calls them is a privilege escalation path; restrict and log it.
• Subagent inheritance: a subagent inherits plan, acceptEdits, auto or bypassPermissions from the main session. Anthropic warns that inheriting bypassPermissions gives subagents, which may have different prompts, full autonomous system access. Under a default or dontAsk parent, a subagent's own bypassPermissions value is never applied (v2.1.267 or later).
• Configuration as privilege: project .claude/settings.json, hooks, CLAUDE.md, skills and .mcp.json load by default. Whoever can write those files in the agent's working directory can change its rules and instructions. This is the SDK form of the configuration file attacks described in the Coding Agent Configuration File Attacks guide.

Integrations, API tokens and service accounts

MCP servers

MCP servers can run as stdio subprocesses, connect over HTTP or SSE, or run in-process as SDK servers you define. Tools are named mcp__<server>__<tool>, and MCP tools need explicit permission before Claude can call them.

• Scope approvals per tool: prefer allowedTools: ["mcp__db__query"] over a server wildcard such as mcp__github__*. Unanchored entries like "*" or "mcp__*" are ignored in allow rules, but work in deny rules, where "mcp__*" removes every MCP tool.
• Do not use modes for MCP access: acceptEdits does not approve MCP tools, and bypassPermissions approves them along with almost everything else. Anthropic recommends allowedTools instead.
• Credentials: stdio servers take keys through the env field; remote servers take headers. In .mcp.json, ${VAR} expands environment variables at runtime, so never write a literal token into the file.
• OAuth: the SDK does not run an interactive OAuth flow. A server without a usable token reports needs-auth or failed and the run continues without its tools. Complete OAuth in your application and pass the access token in headers; see the MCP Authorisation Specification Guide.
• Silent fallback: Anthropic notes Claude can fall back to built-in tools when an MCP server is unavailable. Check server status in the system init message before trusting a result.
• Server-side limits: restrict what the server itself can do. Anthropic's database example sets the MCP server read-only so it rejects writes even if the agent emits one.

Choosing and vetting servers is covered in the MCP Security Guide and Local MCP Server Security Guide.

Tool credentials and the proxy pattern

Anthropic's recommended approach is a proxy outside the agent's security boundary that adds credentials to outbound requests. The agent never sees the secret, the proxy enforces an endpoint allowlist, and every request is logged in one place. Two routes exist: a custom tool or MCP server that forwards to a service outside the boundary (no TLS interception needed), or traffic forwarding through a TLS-terminating proxy whose CA the agent trusts. Note that HTTPS_PROXY alone only sees an opaque CONNECT tunnel, and some clients ignore proxy variables.

Anthropic lists files to exclude from any mount, even read-only: .env files, ~/.git-credentials, ~/.aws/credentials, gcloud application default credentials, ~/.azure/, ~/.docker/config.json, ~/.kube/config, .npmrc, .pypirc, service account JSON files and *.pem or *.key files.

Sandboxing and isolation

The permission engine is a gate, not a sandbox. Anthropic states that Bash command parsing matches commands against rules but does not infer whether a command is dangerous from its effects. Run the agent inside an isolation boundary sized to the threat.

For multi-tenant hosting, Anthropic warns not to rely on default options. Pass settingSources: [], set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, point CLAUDE_CONFIG_DIR at a per-tenant directory, pass an explicit per-tenant cwd on every query() call and apply per-tenant egress rules. Server-managed settings still load when the process authenticates with an organisation credential. Broader patterns are in the AI Agent Sandboxing and Code Execution Guide and Agent Egress Control and Network Isolation Guide.

Logging and detection

Three sources give you a usable audit trail. Plan for all three before production.

• Hooks: a PreToolUse hook with no matcher sees every tool call with tool_name, tool_input, session_id, cwd, and agent_id and agent_type inside subagents; PostToolUse and PostToolUseFailure see results. The tool use ID correlates pre and post events.
• OpenTelemetry: set CLAUDE_CODE_ENABLE_TELEMETRY=1 and the standard OTEL_*_EXPORTER variables to export metrics and logs; traces also need CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1. Prompt text and tool inputs are excluded by default; opting in creates a sensitive data store.
• Proxy logs: the credential-injecting proxy is where egress attempts, blocked domains and credential use show up, independent of anything the agent process reports.
• Session state: transcripts live under ~/.claude/projects/ by default and disappear with the container. A SessionStore adapter mirrors them; it drops batches it cannot deliver and emits a mirror_error message, so alert on that if transcripts are evidence.

Useful metrics: agents in bypassPermissions outside sandboxes (target zero), hook deny rate per agent, share of agents with explicit settingSources, credentials in agent environments (target zero) and time to rotate an agent key. Correlating these into investigations is covered in the AI Agent Observability and Incident Response Guide.

Hardening baseline

1. Inventory first: list every service that imports claude-agent-sdk or @anthropic-ai/claude-agent-sdk, its permission mode, tool list, MCP servers and credentials in its environment.
2. Close the tool surface: pair an explicit allowedTools list using scoped rules (Bash(npm test *), Read, Grep) with permissionMode: "dontAsk", and remove tools the agent never needs with bare names in disallowedTools, for example Bash or WebFetch.
3. Write path rules carefully: Edit(path) rules govern all write tools including Write and NotebookEdit; a Write(path) rule is never matched. Use //path for absolute paths, since /path anchors at the working directory.
4. Add a mandatory PreToolUse hook: enforce invariants (no writes outside the workspace, no secrets paths, no external hosts) there, not in canUseTool. Remember a Write|Edit matcher does not see a Bash command writing the same file; block those with the sandbox.
5. Pin settings sources: set settingSources explicitly. Use [] for agents that process untrusted repositories or serve multiple tenants, and add strictMcpConfig: true.
6. Isolate and proxy: run in sandbox-runtime, a hardened container, gVisor or a microVM; route model and tool traffic through a credential-injecting proxy with a domain allowlist; mount code read-only where possible.
7. Bound runs: set maxTurns on sessions and on each subagent's AgentDefinition, because the SDK has no top-level session timeout.
8. Update deliberately: the bundled CLI binary is pinned to the SDK package version. Anthropic recommends taking patch releases continuously and reading the changelog before a minor release.
9. Test before rollout: run a red-team prompt set (instructions hidden in a README, a request to read ~/.aws/credentials, a request to call an unlisted domain) against a staging agent, confirm each is denied and logged, then promote. Roll back by redeploying the previous options object and SDK version.

Human approval design for canUseTool flows is covered in the Human-in-the-Loop for AI Agents Guide.

Common misconfigurations

• Reading allowed_tools as a whitelist. Setting allowed_tools=["Read"] with bypassPermissions still approves Bash, Write and Edit. Anthropic calls this out explicitly.
• Security logic in canUseTool only. Calls approved by acceptEdits, bypassPermissions or a bare allow entry never reach the callback. The TypeScript SDK emits CLAUDE_SDK_CAN_USE_TOOL_SHADOWED in these cases; treat it as a defect.
• Default settings loading on untrusted code. An agent that reviews pull requests with default options loads that repository's CLAUDE.md, hooks, skills and .mcp.json, so the code under review can rewrite the reviewer's instructions. This is prompt injection by configuration; see the Prompt Injection Guide.
• Credentials inside the boundary. Mounting a home directory for convenience exposes cloud, Kubernetes and registry credentials to anything the agent runs.
• acceptEdits assumed to be harmless. It auto-approves rm, mv and sed inside the working directory. In a directory holding real data, that is destructive capability.
• Broad MCP wildcards. mcp__github__* approves every tool the server exposes now and any it adds later, including write and admin tools.

Framework mapping

Practitioner checklist

• Inventory every SDK deployment with its mode, tools, MCP servers and credentials.
• Remove bypassPermissions from any agent not running in a disposable sandbox.
• Pair scoped allowedTools with dontAsk for headless agents and hide unused tools with disallowedTools.
• Enforce non-negotiable rules in a PreToolUse hook, not in canUseTool.
• Set settingSources explicitly; use [], disabled auto memory and per-tenant CLAUDE_CONFIG_DIR for untrusted or multi-tenant work.
• Approve MCP tools individually, keep tokens out of .mcp.json and check server status at init.
• Move the Claude API key and tool credentials into a proxy outside the agent boundary.
• Export hook events, OpenTelemetry signals and proxy logs to your SIEM and alert on denies, mode changes and mirror_error.
• Set maxTurns on every session and subagent.
• Re-test the red-team prompt set after every SDK minor version upgrade.

Standards and references

• Anthropic: Configure permissions (Agent SDK)
• Anthropic: Intercept and control agent behavior with hooks
• Anthropic: Securely deploying AI agents
• Anthropic: Connect to external tools with MCP (Agent SDK)
• Anthropic: Hosting the Agent SDK
• Anthropic: Use Claude Code features in the SDK
• OWASP: LLM06:2025 Excessive Agency
• NIST: SP 800-53 Rev. 5 Security and Privacy Controls

Related NHI Mgmt Group resources: Claude Code Security Guide · Anthropic API Keys Security Guide · MCP Security Guide · AI Agent Sandboxing and Code Execution Guide · AI Coding Agent Incident Playbook