AWS Bedrock AgentCore Gateway MCP 401: OAuth token, audience claim, and credential provider

This runbook covers AgentCore Gateway auth failures on MCP tool calls. For the wider governance picture, see AWS Loom and governing AI agents. For help designing agent identity and least privilege, book a consulting session.

Symptoms

The tool call fails at the Gateway, before the target MCP server does any work.

# No token or an invalid inbound token
HTTP 401 Unauthorized

# Some clients see 403 instead of 401 for the same class of failure
HTTP 403 Forbidden

# In the agent / MCP client logs
Failed to list tools: server returned 401

Observable impact:

• The agent lists no tools, or every tool call fails immediately
• The failure is instant (auth rejects before any tool logic runs), not a timeout
• Works with a manually minted token in a test but fails from the deployed agent, or vice versa

Cause

AgentCore Gateway follows the MCP standard and rejects any request without a valid token. There are two distinct authentication hops, and either can be the culprit:

1. Inbound (caller to Gateway). The Gateway validates the JWT the caller presents. The most common failure is that the token’s aud (audience) or client_id claim does not match an audience entry configured on the Gateway’s inbound authoriser. A missing, expired, or wrong-issuer token fails the same way.
2. Outbound (Gateway to target via credential provider). For a target that is itself OAuth-protected, the Gateway uses an AgentCore Identity OAuth2 credential provider, which needs a valid client_id and client_secret issued by the target’s identity provider. A misconfigured or unauthorised credential provider fails the onward call.

Two facts worth knowing before you debug:

• AgentCore Gateway supports http_streaming only, not SSE. An MCP client defaulting to SSE transport can surface as a connection or auth error.
• Some clients receive 403 instead of 401 for unauthorised requests, so handle both.

Fix

Step 1: Confirm the Gateway is reachable and rejecting on auth

A 401 with no token proves the Gateway is up and enforcing auth (this is expected behaviour, not a fault).

# No token: expect 401 (or 403). This confirms auth enforcement, not an outage.
curl -s -o /dev/null -w "%{http_code}\n" https://your-gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp

Step 2: Inspect the inbound token’s claims

Decode the JWT your caller sends and check the aud and iss claims against what the Gateway expects.

# Decode the JWT payload (no verification, just to read the claims)
echo "$ACCESS_TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | python3 -m json.tool

The aud (or client_id) claim must exactly match one of the audience entries configured on the Gateway’s inbound authoriser. A mismatch here is the single most common cause of the 401.

Step 3: Verify the Gateway inbound authoriser configuration

# Read the gateway's authoriser configuration
aws bedrock-agentcore-control get-gateway \
  --gateway-identifier your-gateway-id \
  --region us-west-2 \
  --query 'authorizerConfiguration'

Confirm the allowed audience and the discovery URL point at the same identity provider that issued the token in Step 2. If you use Amazon Cognito, note it does not support Dynamic Client Registration, so MCP clients that rely on DCR must be given client credentials manually.

Step 4: Check the outbound credential provider (only if the target is OAuth-protected)

If the inbound token is correct but the onward call to the target still fails, the outbound credential provider is the suspect.

# List credential providers and confirm the one your target uses exists
aws bedrock-agentcore-control list-oauth2-credential-providers \
  --region us-west-2

Confirm the provider holds a valid client_id and client_secret issued by the target MCP server’s identity provider, and that the delegation mode (machine-to-machine or on-behalf-of) matches how the agent calls the tool.

Step 5: Confirm the client uses http_streaming, not SSE

If auth is correct but the MCP client still cannot connect, check its transport. AgentCore Gateway supports http_streaming only; point the client at the /mcp endpoint over streamable HTTP rather than SSE.

Validation

With a correctly-scoped token, listing tools through the Gateway should succeed.

# Call the MCP endpoint with a valid token: expect 200 and a tools list
curl -s https://your-gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  -w "\nHTTP %{http_code}\n"

Expected: HTTP 200 and a JSON body listing the registered tools, with no 401 or 403.

Related

• AWS Loom: governing AI agents on AWS - where the Gateway and MCP registration fit in the platform
• Agent sprawl: governing AI agents before they multiply - why consistent identity across agents matters
• AWS Bedrock AgentCore Gateway documentation