A tool name can stay the same while its description or input schema changes. If your application approved only the name, the next request may give Claude a different definition from the one your reviewer saw.
Anthropic's September 22, 2026 API release adds MCP tool-list recording and pinning alongside inline tool definitions. Applications can keep a fetched list across requests or supply a chosen list themselves. Decide when that list becomes trusted: before the first action, or after an already enabled connector has handled a request.
Use a reviewed snapshot before allowing sensitive work, and treat a replacement as a new review. The procedure below is our engineering recommendation, based on the documented API. General Analysis has not tested this beta against a live MCP integration.
What the new beta preserves#
On the Claude API, send mcp-client-2026-09-15. When the API fetches a server's tools, its response includes an mcp_tool_listing block. Returning the assistant message unchanged, including that block, makes later requests reuse the recorded list. Keep the header on requests carrying it. Alternatively, put the reviewed entries in the MCP toolset's tools field. Pinning reference.
The new inline-tools-2026-09-15 beta also lets a tool_addition carry a definition instead of just a reference. An application can replace a definition under the same name later in the conversation. Adding an MCP toolset this way requires both headers; connection details remain in mcp_servers. These additions are documented for the Claude API. Do not infer their availability from the older connector's broader platform support. Inline tool definitions.
The date in a beta header is its identifier. September 22 is the dated release entry for this development.
See how your AI systems hold up under real attacks
General Analysis maps AI applications and agents, red teams prompts, retrieval, tools, MCP servers, browser actions, permissions, and business workflows, then turns findings into evidence your team can reproduce and retest.
Put review before the first action#
An mcp_tool_listing is returned as part of a response. The connector can also execute tools and return their results in that response. Reading the listing afterward therefore does not establish that a human approved those definitions before use. Inspect content blocks by type; a parser that assumes content[0] is the answer will also need updating. Connector response types.
For a workflow that requires advance review, collect definitions separately. MCP's tools/list method supports pagination; follow every nextCursor. Use the intended authorization context, because a server's available tools can depend on the credentials presented. Save the complete discovery response for review, then project the reviewed fields into Claude's supported pin format.
Consider a hypothetical support server with a lookup_ticket tool. Its first schema takes a ticket ID. A later schema adds an optional destination for exporting the result. Even if the name is unchanged, the reviewer now has a different data-transfer decision. A description-only change also deserves review because it changes text the model receives.
Our recommended admission procedure is:
- Record the server endpoint, authenticated principal, tenant, discovery time, and full tool metadata. Store credential references, never bearer tokens, in this record.
- Review descriptions and schemas against the intended task. Confirm resource access separately with the service owner.
- Save an immutable approved snapshot and its digest. Bind the approval to the endpoint and identity context as well as the tool definitions.
- Build the first action-capable request from that snapshot. Stop if the approved snapshot or identity binding is missing.
The digest is an application integrity check. It does not certify the remote implementation. Our MCP server security guide covers the surrounding supply-chain and tool-poisoning risks.
Configure the reviewed toolset#
This illustrative Messages API excerpt exposes one invented support tool. Replace its definition with the exact reviewed server metadata; it is not a runnable request. The model, messages, server URL, and credential configuration are omitted. Send mcp-client-2026-09-15 as the beta header.
Code source: illustrative; fields follow Anthropic's MCP toolset configuration and pinning reference.
{
"tools": [
{
"type": "mcp_toolset",
"mcp_server_name": "support",
"default_config": { "enabled": false },
"configs": {
"lookup_ticket": { "enabled": true }
},
"tools": [
{
"name": "lookup_ticket",
"description": "Read a support ticket by ID.",
"input_schema": {
"type": "object",
"properties": {
"ticket_id": { "type": "string" }
},
"required": ["ticket_id"],
"additionalProperties": false
}
}
]
}
]
}
Only the named tool is enabled. The server must still check whether the authenticated principal may read the requested ticket. A valid ID and a read-only description do not prove access to that customer's records.
Keep Messages API configuration separate from Managed Agents tool approvals. That product has its own permission policies and confirmation events. This excerpt does not add an approval pause to the Messages API connector.
Decide which changes invalidate approval#
Use the following review decisions as an application policy, not as behavior the beta enforces automatically.
| Observed change | Recommended decision |
|---|---|
| New tool or changed description/schema | Compare with the approved snapshot; require review before offering the replacement. |
| Same definitions, different endpoint or principal | Recheck the service and resource scope; the old binding no longer describes this connection. |
| Same definitions, new server deployment | Review the implementation change through the server's release process. A metadata digest cannot detect it. |
| Access revoked during a conversation | Deny subsequent operations at the server or gateway; a pinned list is not a continuing access grant. |
| Listing missing from a restored conversation | Fail the application's replay validation; do not silently rediscover and call that an approved restore. |
Keep the selected snapshot stable for the conversation. Review newly discovered versions outside the active run, then admit a replacement deliberately. Preserve the old and new snapshots, reviewer decision, affected conversation, and effective change point. This also gives an investigator evidence of what changed without rewriting earlier history.
The MCP tools specification assigns access control and input validation to servers and recommends confirmation for sensitive operations in clients. Implement those checks where the action happens. A stable catalog can still describe an overprivileged tool.
Verify replay and limits before rollout#
Start with a non-production server and synthetic records. Check that restoring a conversation preserves the same listing, headers, and identity binding. Change a test description and confirm that your application requires a new review. Also check that revoked access fails at the server even when the client still holds the old snapshot. These are proposed acceptance checks, not results from an experiment.
If you use inline definitions, keep tool changes in application-owned system messages. Anthropic warns against putting raw tool output or retrieved text in that role because it grants the content operator authority. Its placement rules also prohibit tool-change blocks immediately after a paused assistant turn; resume that turn before applying the change.
Finally, retention belongs in the rollout decision. Anthropic lists the MCP connector as ineligible for Zero Data Retention. Keep access and retention rules for your own snapshots and review records, which can reveal internal tool names and data schemas.
For each sensitive operation, keep the approved snapshot ID with the principal and the server's authorization result. That gives an investigator a way to distinguish an unreviewed definition change from a call that exceeded the user's access.
Frequently asked questions
- Does MCP tool-list pinning freeze the server's code?
No. It preserves the tool definitions supplied to Claude. A remote server can change its implementation without changing those definitions. Review server deployments and enforce resource access independently.
- Is mcp_tool_listing a human approval request?
No. It records the list fetched while producing a response. That response can also contain MCP calls and results. If review must precede execution, supply an approved list before the first action-capable request and enforce approval at the server or gateway.
