Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

MCP protocol contract

Understand the requirements for implementing the Model Context Protocol (MCP) in Amazon Bedrock AgentCore Runtime so that agents can call tools and agent servers. These requirements apply to MCP servers on both compute types, microVMs and Instances.

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

AgentCore Runtime routes each request to a microVM based on a session ID. It takes the session ID from a client request header, or generates one if the request doesn’t include it. Requests with the same session ID go to the same microVM while the session is active. On Instances, requests with the same session ID go to the same instance session. For more information, see Use isolated sessions for agents and, for Instances, Session. Sending the same session ID on related requests helps you:

The header that AgentCore Runtime uses for the session ID depends on the MCP protocol version, because version 2026-07-28 removes the Mcp-Session-Id header. For more information, see Key changes in the MCP 2026-07-28 specification.

Version 2026-07-28 and later

AgentCore Runtime uses X-Amzn-Bedrock-AgentCore-Runtime-Session-Id as the session ID. For backward compatibility, it still accepts Mcp-Session-Id. If the client sends both headers, AgentCore Runtime uses Mcp-Session-Id. Each response header returns the value that the client sent in the same request header, even if the two values differ. If the client sends only one of the headers, both response headers use its value. If the client sends neither, both use a session ID that the service generates.

Version 2025-11-25 and earlier

AgentCore Runtime uses Mcp-Session-Id as the session ID (for the MCP specification, see MCP Streamable HTTP Transport). Clients must capture the Mcp-Session-Id returned in the response and include it in all subsequent requests. The service doesn’t use X-Amzn-Bedrock-AgentCore-Runtime-Session-Id to route requests in this version.

Stateless MCP ( stateless_http=True ):

Stateful MCP ( stateless_http=False ):

For more information about stateful MCP session management, see the MCP session management specification.

Server requirements

Whether you use direct code deployment or a container image, your MCP server must meet these requirements:

You can change the serving port and the InvokeAgentRuntime POST path with protocolConfiguration. See Path requirements for the default paths. For configuration examples, see Configure your agent’s serving port and invocation path.

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:

/ping - GET (Recommended)

Purpose

Reports whether your MCP server is healthy, independent of the MCP protocol version that your server implements. AgentCore Runtime doesn’t require /ping, but we recommend that every MCP server implement it. With GET /ping, your server can also report HealthyBusy while it runs background work, so that AgentCore Runtime doesn’t end the session for being idle. For more information, see Runtime session lifecycle management.

Response format

To be detected, /ping must:

Health probes

AgentCore Runtime probes your server to decide when it is ready to serve traffic and whether it is still healthy. To implement the recommended health endpoint, see /ping - GET (Recommended).

Readiness check when a session starts

When a new session starts, AgentCore Runtime sends GET /ping to your server’s serving port. Any response other than 502 or 429 shows that your server accepted the connection. This includes 404 and 405. AgentCore Runtime then treats your server as ready. If your server doesn’t implement /ping, a 404 Not Found for GET /ping in your access log is expected and harmless.

Health checks during the session

After your server is serving, AgentCore Runtime continues to check health. It first checks whether your server implements GET /ping. If it does, AgentCore Runtime uses GET /ping for the rest of the session. Otherwise, it sends an MCP ping request: a POST to your MCP path with a JSON-RPC ping method and the Accept: application/json, text/event-stream header. This fallback supports servers on MCP protocol version 2025-11-25 and earlier, in both stateful and stateless mode, and servers on version 2026-07-28.

A server on version 2026-07-28 might reject the ping request, because that version removed the ping method and the initialize handshake. If your server returns HTTP 400 to ping, AgentCore Runtime sends an initialize request. If that request also returns 400, AgentCore Runtime treats your server as healthy unless it stops responding or returns server errors. It also writes a one-time message to your agent’s logs that recommends implementing /ping. Other error responses to ping or initialize can fail the health check.

Error handling

AgentCore Runtime returns errors as JSON-RPC 2.0 error responses. Error codes and HTTP status codes depend on the MCP-Protocol-Version request header:

The following table lists the error for each runtime exception.

Example error response:

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

Responses from your MCP server

When your MCP server returns one of the following status codes, the service returns that status code and the response body to the client. For any other status code, the service returns RuntimeClientError.

Retrying RetryableConflictException

ConflictException and RetryableConflictException share error code -32005 and differ by message. The service returns RetryableConflictException when an operation targets a session that is being provisioned or torn down. Retry with short exponential backoff — MCP clients do not auto-retry it. For version 2025-11-25 and earlier, the response is HTTP 200, so inspect the response body to detect it.

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}"