MCP protocol contract - Amazon Bedrock AgentCore
Protocol implementation requirementsContainer requirementsPath requirementsOAuth Authentication Responses

MCP protocol contract

Understand the requirements for implementing the Model Context Protocol (MCP) so that agents can call tools and agent servers.

For example code, see Deploy MCP servers in AgentCore Runtime.

Protocol implementation requirements

Your MCP server must implement these specific protocol requirements:

  • Transport: Stateless streamable-http only - Ensures compatibility with AWS's session management and load balancing

  • Session Management: Platform automatically adds Mcp-Session-Id header for session isolation, servers must support stateless operation so as to not reject platform generated Mcp-Session-Id header

Container requirements

Your MCP server must be deployed as a containerized application meeting these specifications:

  • Host: 0.0.0.0

  • Port: 8000 - Standard port for MCP server communication (different from HTTP protocol)

  • Platform: ARM64 container - Required for compatibility with AWS Amazon Bedrock AgentCore runtime environment

Path requirements

/mcp - POST

Purpose

Receives MCP RPC messages and processes them through your agent's tool capabilities, complete pass-through of InvokeAgentRuntime API payload with standard MCP RPC messages

Response format

JSON-RPC based request/response format, supporting both application/json and text/event-stream as response content-types

Use cases

The /mcp endpoint serves several key purposes:

  • Tool invocation and management

  • Agent capability discovery

  • Resource access and manipulation

  • Multi-step agent workflows

OAuth Authentication Responses

OAuth-configured agents follow RFC 6749 (OAuth 2.0) authentication standards. When authentication is missing, the service returns a 401 Unauthorized response with a WWW-Authenticate header (per RFC 7235), enabling clients to discover the authorization server endpoints through the GetRuntimeProtectedResourceMetadata API.

401 Unauthorized

Returned when the Authorization header is missing or empty.

Response includes WWW-Authenticate header:

WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
Note

SigV4-configured agents return 403 for missing authentication and do NOT include WWW-Authenticate headers.