# 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](https://docs.faustine.ai/agent-gateway/create-a-gateway/).
- An API key for the environment you connect to. See [Create an API key](https://docs.faustine.ai/agent-gateway/api-keys/).
- 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.

```bash
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](https://docs.claude.com/en/docs/agents-and-tools/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.

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

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

2. 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.
3. 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](https://platform.claude.com/docs/en/managed-agents/mcp-connector) 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](https://docs.faustine.ai/agent-gateway/set-confirmation/).

## 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](https://docs.faustine.ai/agent-gateway/scope-a-credential/): limit the key to the operations your code needs.
- [Serving modes: Code and Tools](https://docs.faustine.ai/agent-gateway/serving-modes/): which tools the gateway gives Claude.
- [Call a gateway over REST and OpenAPI](https://docs.faustine.ai/technologies/rest/): call operations from your own code without a model.