Connect the Claude Messages API and Managed Agents

The Claude Messages API and Managed Agents connect to a gateway as a remote MCP server. Anthropic's servers call the gateway for you, so there is no MCP client to run. Both send an API key.

Before you begin

A gateway that serves at least one API. See Create a gateway.
An API key for the environment you connect to. See Create an API key.
An Anthropic API key.

The request body on this page is in the gateway's Connect tab, under Messages API, with your gateway's values filled in.

Call the gateway from the Messages API

A request names the gateway in mcp_servers and turns on its tools with an mcp_toolset entry in tools. Both are required, and the name of the server has to match mcp_server_name. The request also sends the beta header anthropic-beta: mcp-client-2025-11-20.

Replace <GATEWAY_KEY> with the gateway API key. ANTHROPIC_API_KEY is your Anthropic key.

terminal

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://gateway.faustine.ai/<workspace>/<gateway>/mcp",
        "name": "<gateway>",
        "authorization_token": "<GATEWAY_KEY>"
      }
    ],
    "tools": [{ "type": "mcp_toolset", "mcp_server_name": "<gateway>" }],
    "messages": [{ "role": "user", "content": "List the contacts." }]
  }'

The response contains the tool calls Claude made to the gateway and their results, followed by Claude's answer. For the fields of mcp_servers and mcp_toolset, see MCP connector in the Claude docs.

Connect a Managed Agent

A Managed Agent keeps the gateway's address in the agent and the key in a vault, so the key is never part of the agent definition.

In the agent, declare the gateway in mcp_servers and turn on its tools.

{
  "mcp_servers": [
    { "type": "url", "name": "<gateway>", "url": "https://gateway.faustine.ai/<workspace>/<gateway>/mcp" }
  ],
  "tools": [{ "type": "mcp_toolset", "mcp_server_name": "<gateway>" }]
}

In a vault, add a static_bearer credential whose mcp_server_url is the same MCP URL and whose token is the gateway API key.
Create the session with the vault in vault_ids.

Anthropic adds the key to each call the agent makes to that URL. For the vault's fields, see MCP connector for Managed Agents in the Claude docs.

What you see after the first call

In the portal, the request appears in the gateway's Logs tab, and the Messages API or Managed Agents card in the Connect tab shows when the client was last seen.

A call to an operation that requires confirmation is refused by default for an API key, because there is no person to ask. To change this, see Set how a credential confirms writes.

Troubleshooting

Symptom	Cause	Fix
The Messages API returns a validation error for `mcp_servers`	The request has `mcp_servers` without an `mcp_toolset` entry in `tools`, or the beta header is missing.	Send both, with the same server name, and the `anthropic-beta` header.

Next steps

Scope a key or user: limit the key to the operations your code needs.
Serving modes: Code and Tools: which tools the gateway gives Claude.
Call a gateway over REST and OpenAPI: call operations from your own code without a model.