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:

MCP session management and microVM stickiness

The Model Context Protocol (MCP) uses the Mcp-Session-Id header to manage session state and route requests. For the MCP specification, see MCP Streamable HTTP Transport.

MicroVM Stickiness : Amazon Bedrock AgentCore uses the Mcp-Session-Id header to route requests to the same microVM instance. Clients must capture the Mcp-Session-Id returned in the response and include it in all subsequent requests to ensure session affinity. Without a consistent session ID, each request may be routed to a new microVM, which may result in additional latency due to cold starts.

Stateless MCP ( stateless_http=True ):

Stateful MCP ( stateless_http=False ):

For more details on stateful MCP session management, see the MCP session management specification.

Container requirements

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

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:

Error handling

MCP servers return errors as standard JSON-RPC 2.0 error responses. Most errors are carried in the JSON-RPC error object with an HTTP 200 status code, as required by the MCP specification. Only authentication, authorization, and protocol-level request errors use non-200 HTTP status codes. The following table maps each runtime exception to its JSON-RPC error code, HTTP status code, and message. Some exceptions share a JSON-RPC error code but return different messages, so they are listed as separate rows.

ConflictException and RetryableConflictException both use JSON-RPC error code -32005 (HTTP 200) but are distinguished by their message. The service returns RetryableConflictException (Session operation in progress, please retry) when a second operation targets a session while the service is provisioning or tearing down that session. Because MCP returns HTTP 200 with the error in the JSON-RPC body, the caller must inspect the response body and retry with short exponential backoff — MCP clients do not auto-retry it.

Example error response:

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "error": {
    "code": -32005,
    "message": "Session operation in progress, please retry"
  }
}

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://webproxy.poorya-velaei-d67.workers.dev/https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"