Managed Agents Tools

Server tools vs client tools

Recommendation: Enable all prebuilt tools via agent_toolset_20260401, then disable individually as needed.

Versioning: The toolset is a versioned, static resource. When underlying tools change, a new toolset version is created (hence _20260401) so you always know exactly what you’re getting.

Agent Toolset

The agent_toolset_20260401 provides these built-in tools:

Enable the full toolset:

Per-Tool Configuration

Override defaults for individual tools. This example enables everything except bash:

Permission Policies

Control when server-executed tools (agent toolset + MCP) run automatically vs wait for approval. Does not apply to custom tools.

Responding to always_ask: Send a user.tool_confirmation event with tool_use_id from the triggering agent_tool_use/mcp_tool_use event:

The optional message on a deny is delivered to the agent so it can adjust its approach.

To enable only specific tools, flip the default off and opt-in per tool:

Custom Tools (Client-Side)

Custom tools are executed by your application, not Anthropic. The flow:

1. Agent decides to use the tool → session emits a agent.custom_tool_use event with inputs
2. Session goes idle waiting for you
3. Your application executes the tool
4. You send back a user.custom_tool_result event with the output
5. Session resumes running

No permission policy needed — you’re the one executing.

MCP Servers

MCP (Model Context Protocol) servers expose standardized third-party capabilities (e.g. Asana, GitHub, Linear). Configuration is split across agent and vault:

1. Agent creation declares which servers to connect to (type, name, url — no auth). The agent’s mcp_servers array has no auth field.
2. Vault stores the OAuth credentials. Attach via vault_ids on session create.

This keeps secrets out of reusable agent definitions. Each vault credential is tied to one MCP server URL; Anthropic matches credentials to servers by URL.

Agent side — declare servers (no auth):

Session side — attach vault:

💡 Per-tool enablement (empirical): mcp_toolset has been observed accepting default_config: {enabled: false} + configs: [{name, enabled: true}] for an allowlist pattern. The API ref shows only the minimal {type, mcp_server_name} form.

💡 Changing tools/MCP servers on a running session: sessions.update() can replace agent.tools and agent.mcp_servers while the session is idle — a session-local override that doesn’t touch the agent object. vault_ids is create-only. See shared/managed-agents-core.md → Updating the agent configuration mid-session.

Large tool outputs. If a tool returns more than 100,000 characters (roughly 25,000 tokens), the output is automatically offloaded to a file in the sandbox — the agent receives a truncated preview plus the file path and can read the full content. No configuration required. The threshold is in characters, not tokens, and applies to built-in agent tools as well as MCP tools.

Invalid vault credentials don’t block session creation. If a vault credential is invalid for a declared MCP server, the session still creates successfully; a session.error event describes the MCP auth failure, and auth retries on the next session.status_idle → session.status_running transition.

⚠️ MCP auth tokens ≠ REST API tokens. Hosted MCP servers (mcp.notion.com, mcp.linear.app, etc.) typically require OAuth bearer tokens, not the service’s native API keys. A Notion ntn_ integration token authenticates against Notion’s REST API but will not work as a vault credential for the Notion MCP server. These are different auth systems.

Vaults — the credential store

Vaults store credentials that Anthropic manages on your behalf. Two credential categories:

• MCP credentials (mcp_oauth, static_bearer) — keyed by mcp_server_url. When the agent connects to a server at that URL, the token is injected automatically. Matching is normalized, not byte-exact: scheme and host are lowercased, and default ports and trailing slashes are stripped, so host casing, an explicit default port, or a trailing slash won’t break the match. A different path, subdomain, or non-default port will. If nothing matches, the connection is attempted unauthenticated. mcp_oauth tokens are auto-refreshed via the standard OAuth 2.0 refresh_token grant. This is the only way to authenticate MCP servers.
• Environment variables (environment_variable) — keyed by secret_name (the env var name). The sandbox sees only an opaque placeholder; the real secret is substituted into the outbound request at egress. Use this for any service that authenticates through an environment variable: CLIs (aws, gcloud, stripe), SDKs, or direct curl calls from the bash tool.

Secret fields you supply (token, access_token, refresh_token, client_secret, secret_value) are write-only — never returned in API responses.

Credentials and the sandbox

Vaults store credentials; those credentials never enter the sandbox. This is a deliberate security boundary — code running in the sandbox (including anything the agent writes) cannot read or exfiltrate a vaulted credential, even under prompt injection. Instead, credentials are injected by Anthropic-side proxies after a request leaves the sandbox:

• MCP tool calls are routed through an Anthropic-side proxy that fetches the credential from the vault and adds it to the outbound request.
• Git operations on attached GitHub repositories (git pull, git push, GitHub REST calls) are routed through a git proxy that injects the github_repository resource’s authorization_token the same way.
• Environment-variable credentials appear in the sandbox as an opaque placeholder; the real value replaces the placeholder at egress, on requests to the credential’s allowed hosts only. Substitution covers request headers and body only — a secret embedded in the URL path is never substituted, so path-secret endpoints (e.g. Slack incoming-webhook URLs) can’t be vaulted; use header-based auth instead (for Slack: a bot token in Authorization via chat.postMessage).

When vault credentials don’t fit (e.g. self-hosted sandboxes — environment_variable is not yet supported there), register a custom tool: the agent emits agent.custom_tool_use, your orchestrator (which already holds the credential) executes the call and returns user.custom_tool_result over the same authenticated event stream. No public endpoint is exposed; the sandbox never sees the secret. See shared/managed-agents-client-patterns.md → Pattern 9.

Do not put API keys in the system prompt or user messages as a workaround — they persist in the session’s event history.

Formerly known internally as TATs (Tool/Tenant Access Tokens).

Flow:

1. Create a vault (client.beta.vaults.create(...)) — one per tenant/user, or one shared, depending on your model
2. Add credentials to it (client.beta.vaults.credentials.create(...)) — MCP credentials are keyed by MCP server URL; environment-variable credentials by secret_name
3. Reference the vault on session create via vault_ids: ["vlt_..."]
4. Anthropic auto-refreshes OAuth tokens before they expire and substitutes secrets at runtime

MCP OAuth credential shape:

The refresh block is what enables auto-refresh — token_endpoint is where Anthropic posts the refresh_token grant. token_endpoint_auth is a discriminated union:

Omit refresh entirely if you only have an access token with no refresh capability — it’ll work until it expires, then the agent loses access.

💡 Getting an OAuth token. How you obtain the initial access and refresh tokens depends on the MCP server — consult its documentation. Once you have them, store them in a vault credential using the shape above; Anthropic auto-refreshes via the refresh.token_endpoint from there.

Environment-variable credential shape:

networking.allowed_hosts controls which outbound hosts the secret can be substituted for — {"type": "limited", "allowed_hosts": [...]} or {"type": "unrestricted"} if you can’t enumerate the domains in advance. Limiting is strongly recommended: it prevents the key from ever being sent to unauthorized hosts.

injection_location (optional, sibling of networking) controls where in the outbound request the secret is substituted — {header: bool, body: bool}. The two are independent: allowed_hosts scopes which hosts a substituted request can target; injection_location scopes which parts of the request the secret is substituted into across all of those hosts. Most services read an API key from a request header, so {"header": true} is the narrower configuration — request bodies are often assembled from content the agent is working with, making the body the broader exposure surface. A placeholder in a disabled location is neither substituted nor stripped — the literal opaque placeholder string is sent to the third party in that location.

A credential must have at least one location enabled; a create or update that would disable both returns 400, as does explicit null for the object or either field (omit instead). The response always returns both fields with their resolved values.

⚠️ Credentials created in the Console are header-only by default — unlike the API, where omitting the field enables both. If your client sends the secret in the request body (a form-encoded token request, for example), the placeholder passes through literally and the service rejects it with its own authentication error. Tick body injection in the Console form, or POST the credential with {"injection_location": {"body": true}}.

⚠️ Two networking layers, both required. networking.allowed_hosts on the credential controls which requests use the secret, not which requests are allowed. The agent must also be able to reach the domain at the environment level (unrestricted, or the host listed in the environment’s allowed_hosts — see shared/managed-agents-environments.md). A domain missing from either layer means the secret-substituted request fails.

⚠️ Client-side validation caveat. Substitution happens at egress, not inside the sandbox — clients that validate the credential format locally before making a network request (e.g. a CLI that checks the key starts with sk-) will see the opaque placeholder and may fail at startup. If a client rejects the credential before any network call, that’s why.

💡 Scope the key minimally. The agent can do anything the key allows; a key with broader permissions than the task needs increases the blast radius if the agent behaves unexpectedly.

Not supported with self-hosted sandboxes — environment_variable credentials require Anthropic-managed egress. See shared/managed-agents-self-hosted-sandboxes.md.

Constraints (all credential types):

• Unique key per vault. mcp_server_url (MCP credentials) and secret_name (environment-variable credentials) must be unique among active credentials in a vault; duplicates return a 409.
• Keys are immutable. Secret values, display_name, and (on environment-variable credentials) injection_location can be updated; to change mcp_server_url, secret_name, token_endpoint, or client_id, archive the credential and create a new one. Archiving purges the secret and frees the key for a replacement.
• Maximum 20 credentials per vault.
• Credentials are stored as provided and not validated until session runtime — an invalid credential surfaces as an authentication or downstream error during the session, which is emitted but does not block the session from continuing.

Scoping: Vaults are workspace-scoped. Anyone with developer+ role in the API workspace can create, read (metadata only — secrets are write-only), and attach vaults. vault_ids can be set at session create time but not via session update (the SDK docstring says “Not yet supported; requests setting this field are rejected”).

Skills

Skills are reusable, filesystem-based resources that provide your agent with domain-specific expertise: workflows, context, and best practices that transform general-purpose agents into specialists. Unlike prompts (conversation-level instructions for one-off tasks), skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations.

Skills reach the agent two ways: attached through the agent’s skills array, or loaded from a GitHub repository mounted on the session (see § Skills from a GitHub repository below). The agent automatically uses them when relevant to the task at hand:

Max 20 skills per agent. Agent creation uses managed-agents-2026-04-01; the separate Skills API (for managing custom skill definitions) uses skills-2025-10-02.

Enabling skills on a session

Skills are attached to the agent definition via agents.create():

Python:

Skill reference fields:

version is optional on both kinds and defaults to "latest" — it is not custom-skill-only.

Skills from a GitHub repository

Skills can also live in your codebase. When a session mounts a repository via the github_repository resource (see shared/managed-agents-environments.md → GitHub Repositories), the repository’s root .claude/skills directory is scanned at session start, and each skill found becomes available to the agent: it sees each discovered skill’s name, description, and sandbox path, and reads the skill’s SKILL.md (plus any scripts/resources it ships) when a task matches.

The agent can discover any skill in .claude/skills/<skill-name>/ — one directory level deep at the repository root. Skills in the following locations are not discoverable: a bare .claude/skills/SKILL.md (no skill directory), anything nested deeper (.claude/skills/tools/code-review/SKILL.md), a skills/ directory outside .claude, or a .claude/skills inside a package subdirectory (though those can still surface when the agent reads files under that subtree). The SKILL.md format is the same as uploaded custom skills.

⚠️ Repository skills are agent instructions — treat them as part of your trust boundary. Anyone who can commit to a mounted repository (a merged external PR, a compromised dependency, a contributor) can add or edit .claude/skills/ content, and the platform loads it at session start with no review step — where session tools like bash and web_fetch give injected instructions real capability. Only mount repositories you trust, and audit .claude/skills/ before mounting one with external contributors.

Rules:

• Cloud sandboxes only — self-hosted sandboxes don’t support github_repository resources, so they can’t load repository skills.
• Scanned once, at session start, from the repository state checked out then (the resource’s checkout branch/commit, else the default branch). Commits pushed mid-session are not picked up — start a new session for updated skills. Repositories added to a running session are not scanned either.
• Coexists with attached skills. If a repository skill shares a name with an attached skill (or a skill from another mounted repo), both are available, each announced with its own path.

Skills API