mcp_authentication_failed_error

If the vault holds a credential you believe covers this server, and it still connects unauthenticated

1. 1 Read the URL as stored rather than as you remember it. GET /v1/agents/{agent_id} returns mcp_servers[] with each name and url; pass ?version= to read an earlier version if the agent has been modified since the credential was created. A session can also replace agent.mcp_servers for itself without creating a new agent version, so on a live session read the session rather than the agent. An agent may declare up to 20 MCP servers and a vault holds at most 20 credentials; each URL is matched on its own.
2. 2 Compare that string to the credential's mcp_server_url. Normalization covers scheme and host casing, a default port, and a trailing slash, and nothing else: https://api.example.com/mcp matches https://API.example.com/mcp/ and https://api.example.com:443/mcp, but not https://api.example.com/mcp/v1, https://mcp.example.com/mcp, or https://api.example.com:8443/mcp.
3. 3 mcp_server_url is locked after creation, so the fix is to archive the credential and create a replacement keyed on the declared string — archiving purges the secret and frees the key for the new one. If the session attaches several vaults, the first vault with a match wins, so a stale credential in an earlier vault can shadow the correct one.

# The credential key is immutable: archive, then recreate on the exact URL.
curl --fail-with-body -sS -X POST \
  "https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

curl --fail-with-body -sS "https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "display_name": "Example MCP",
  "auth": {
    "type": "static_bearer",
    "mcp_server_url": "https://api.example.com/mcp/v1",
    "token": "your-token"
  }
}
EOF

If the credential is mcp_oauth and the URLs already match

1. 1 Ask Anthropic what happened. mcp_oauth_validate returns one of three statuses and each implies a different action: valid means the token works and the problem is elsewhere, invalid means the grant is gone or the authorization server rejected the refresh with a 4xx and the end user has to re-authorize, unknown means a transient 5xx, 429 or network failure and you should wait and retry.
2. 2 Anthropic only refreshes when you supplied a refresh block. Without one, the validation response comes back with "has_refresh_token": false and refresh.status: "no_refresh_token", and the access token stays whatever you last stored. With one, refresh.token_endpoint_auth.type has to match what your authorization server actually accepts — none for a public client, client_secret_basic, or client_secret_post.
3. 3 Rotate the parts you can. access_token, expires_at and refresh.refresh_token are updatable and running sessions re-resolve credentials without a restart; token_endpoint and client_id are locked after creation, so changing either means archive and recreate. Subscribe to the vault_credential.refresh_failed webhook so a dead grant reaches you before the next session does.

# Rotate the token in place. Structural fields cannot be updated.
curl --fail-with-body -sS \
  "https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "auth": {
    "type": "mcp_oauth",
    "access_token": "xoxp-new-...",
    "expires_at": "2099-12-31T23:59:59Z",
    "refresh": {"refresh_token": "xoxe-1-new-..."}
  }
}
EOF

If the credential is static_bearer

1. 1 Anthropic documents one validation endpoint and it is for mcp_oauth credentials, so there is nothing to ask about this one: credentials "are stored as provided and are not validated until session runtime." Test the token yourself with the same initialize request the OAuth probe makes, and read the status code rather than the body.
2. 2 Split the result. If the server accepts the token from curl but the session still fails, the credential is not reaching it and the URL match above is your bug. If the server rejects it from curl too, the token is wrong, revoked, or issued for a different workspace or account than the one the server expects.
3. 3 static_bearer sends the token as a bearer token and nothing else. An mcp_servers[] entry takes only type, name and url, and the two MCP credential types are mcp_oauth and static_bearer, so there is no documented way to send X-API-Key or any other header from Managed Agents. A server that insists on a custom header has to accept Authorization: Bearer as well, or sit behind something that translates. A fixed key is out of scope of the MCP authorization spec, which makes authorization OPTIONAL — not in conflict with it.

# The same handshake step the vault probe reports as "initialize".
curl -sS -o /dev/null -w '%{http_code}\n' -X POST \
  https://api.example.com/mcp/v1 \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2025-11-25",
        "capabilities":{},
        "clientInfo":{"name":"curl","version":"1.0"}}}'

If the MCP server is private and reachable only through an MCP tunnel

1. 1 The tunnel is transport, not authentication. Anthropic says it plainly: "the tunnel carries encrypted traffic to your MCP server but does not authenticate to it. If the upstream MCP server requires its own authentication (OAuth, bearer token), supply it the same way you would for any other MCP server." Configuring OAuth on each MCP server is listed as your organization's responsibility, not Anthropic's.
2. 2 Key the credential on the tunnel URL, never the internal one. Each server gets a hostname under your tunnel domain, and when you attach it to a Managed Agents session in the Console you supply the Subdomain and the Path while the "Resolves to" line shows the exact URL. Copy that string into mcp_server_url; https://mcp.internal.svc:8080/mcp will never normalize to it. The path is your server's own — "the proxy forwards the path untouched."
3. 3 Check which error you actually have before touching the tunnel stack. A routing or TLS fault in the tunnel is a network failure, which Anthropic classes as mcp_connection_failed_error; this page's error means the request reached something that wanted a credential. Note also that MCP tunnels are a research preview, provided "as-is" without any uptime, support, or continuity commitment, and tunnels created through the Console are not available as connectors in claude.ai.

If the URL that has to match keeps moving, or one vault token is standing in for many upstream servers

1. 1 Give the agent one origin that does not move. Each MCP route on the gateway is a URL you own, and a single deployment fronts any number of upstream MCP servers, one route per upstream — so the string in mcp_servers[].url and the string in mcp_server_url stop tracking whichever internal host and path the server happens to have this quarter.
2. 2 The vault then holds one credential to the gateway, and the gateway owns the upstream side. mcp-token-exchange-inbound brokers a separate credential per upstream, storing and refreshing each user's grant; set-upstream-api-key-inbound covers an upstream that only takes a static key. The token presented to the gateway is never the token the gateway sends upstream, which is what the spec's MUST NOT on token passthrough requires.
3. 3 If the upstream is private, the Zuplo secure tunnel dials outbound from inside your network and the gateway routes to internal DNS names, so nothing has to be exposed to the internet and there is no inbound rule to write.

Something else

Whatever the credential is, diagnose it in this order and stop at the first failure. One: was anything sent — does a credential in an attached vault match the declared URL once both are normalized? Two: does the token still work when you present it yourself? Three: can Anthropic renew it — is there a refresh block, and does its token_endpoint_auth match what your authorization server accepts? Because session creation validates none of this, session.error on the event stream and the vault_credential.refresh_failed webhook are the only signals you get, and the connection will keep retrying on every idle-to-running transition until the configuration changes.