Deploy MCP servers in AgentCore Runtime

Amazon Bedrock AgentCore Runtime lets you deploy and run Model Context Protocol (MCP) servers in the AgentCore Runtime. This guide walks you through creating, testing, and deploying your first MCP server.

For an example, see https://github.com/awslabs/amazon-bedrock-agentcore-samples/tree/main/01-tutorials/01-AgentCore-runtime/02-hosting-MCP-server.

In this section, you learn:

For more information about MCP, see MCP protocol contract.

How Amazon Bedrock AgentCore supports MCP

When you configure a Amazon Bedrock AgentCore Runtime with the MCP protocol, the service expects MCP server containers to be available at the path 0.0.0.0:8000/mcp, which is the default path supported by most official MCP server SDKs.

Amazon Bedrock AgentCore requires stateless streamable-HTTP servers because the Runtime provides session isolation by default. The platform automatically adds a Mcp-Session-Id header for any request without it, so MCP clients can maintain connection continuity to the same Amazon Bedrock AgentCore Runtime session.

The payload of the InvokeAgentRuntime API is passed through directly, allowing RPC messages of protocols like MCP to be easily proxied.

Prerequisites

Step 1: Create your MCP server

Install required packages

First, install the MCP package:

pip install mcp

Create your first MCP server

Create a new file called my_mcp_server.py:

# my_mcp_server.py

from mcp.server.fastmcp import FastMCP
from starlette.responses import JSONResponse

mcp = FastMCP(host="0.0.0.0", stateless_http=True)

@mcp.tool()
def add_numbers(a: int, b: int) -> int:
    """Add two numbers together"""
    return a + b

@mcp.tool()
def multiply_numbers(a: int, b: int) -> int:
    """Multiply two numbers together"""
    return a * b

@mcp.tool()
def greet_user(name: str) -> str:
    """Greet a user by name"""
    return f"Hello, {name}! Nice to meet you."

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

Understanding the code

Step 2: Test your MCP server locally

Start your MCP server

Run your MCP server locally:

python my_mcp_server.py

You should see output indicating the server is running on port 8000.

Test with MCP client

From a new terminal, create a new file my_mcp_client.py and execute it using python my_mcp_client.py

# my_mcp_client.py

import asyncio

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    mcp_url = "http://localhost:8000/mcp"
    headers = {}

    async with streamablehttp_client(mcp_url, headers, timeout=120, terminate_on_close=False) as (
        read_stream,
        write_stream,
        _,
    ):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            tool_result = await session.list_tools()
            print(tool_result)

asyncio.run(main())

You can also test your server using the MCP Inspector as described in Local testing with MCP inspector.

Step 3: Deploy your MCP server to AWS

Install deployment tools

Install the AgentCore starter toolkit:

pip install bedrock-agentcore-starter-toolkit

You use the starter toolkit to deploy your agent to AgentCore Runtime.

Create a project folder with the following structure:

## Project Folder Structure

your_project_directory/
├── mcp_server.py # Your main agent code
├── requirements.txt # Dependencies for your agent
└── __init__.py # Makes the directory a Python package

Create a new file called requirements.txt, add the following to it:

mcp

requirements.txt specifies the requirements that the agent needs for deployment to AgentCore Runtime.

Configure your MCP server for deployment

Before configuring your deployment, you need to set up a Cognito user pool for authentication as described in Set up Cognito user pool for authentication. This provides the OAuth tokens required for secure access to your deployed server.

After setting up authentication, create the deployment configuration:

agentcore configure -e my_mcp_server.py --protocol MCP

This will start a guided prompt workflow:

Deploy to AWS

Deploy your agent:

agentcore launch

This command will:

After deployment, you'll receive an agent runtime ARN that looks like:

arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/my_mcp_server-xyz123

Step 4: Invoke your deployed MCP server

Test with MCP client (remote)

Before testing, set the following environment variables:

if you pass in an Accept header, it must follow the MCP standard. Acceptable media types are application/json and text/event-stream.

Create a new file my_mcp_client_remote.py and execute it using python my_mcp_client_remote.py

import asyncio
import os
import sys

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    agent_arn = os.getenv('AGENT_ARN')
    bearer_token = os.getenv('BEARER_TOKEN')
    if not agent_arn or not bearer_token:
        print("Error: AGENT_ARN or BEARER_TOKEN environment variable is not set")
        sys.exit(1)
    
    encoded_arn = agent_arn.replace(':', '%3A').replace('/', '%2F')
    mcp_url = f"https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/{encoded_arn}/invocations?qualifier=DEFAULT"
    headers = {"authorization": f"Bearer {bearer_token}","Content-Type":"application/json"}
    print(f"Invoking: {mcp_url}, \nwith headers: {headers}\n")

    async with streamablehttp_client(mcp_url, headers, timeout=120, terminate_on_close=False) as (
        read_stream,
        write_stream,
        _,
    ):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            tool_result = await session.list_tools()
            print(tool_result)

asyncio.run(main())

You can also test your deployed server using the MCP Inspector as described in Remote testing with MCP inspector.

Appendix

Set up Cognito user pool for authentication

Create a new file setup_cognito.sh and add the following content.

#!/bin/bash

# Create User Pool and capture Pool ID directly
export POOL_ID=$(aws cognito-idp create-user-pool \
  --pool-name "MyUserPool" \
  --policies '{"PasswordPolicy":{"MinimumLength":8}}' \
  --region $REGION | jq -r '.UserPool.Id')

# Create App Client and capture Client ID directly
export CLIENT_ID=$(aws cognito-idp create-user-pool-client \
  --user-pool-id $POOL_ID \
  --client-name "MyClient" \
  --no-generate-secret \
  --explicit-auth-flows "ALLOW_USER_PASSWORD_AUTH" "ALLOW_REFRESH_TOKEN_AUTH" \
  --region $REGION | jq -r '.UserPoolClient.ClientId')

# Create User
aws cognito-idp admin-create-user \
  --user-pool-id $POOL_ID \
  --username $USERNAME \
  --region $REGION \
  --message-action SUPPRESS > /dev/null

# Set Permanent Password
aws cognito-idp admin-set-user-password \
  --user-pool-id $POOL_ID \
  --username $USERNAME \
  --password $PASSWORD \
  --region $REGION \
  --permanent > /dev/null

# Authenticate User and capture Access Token
export BEARER_TOKEN=$(aws cognito-idp initiate-auth \
  --client-id "$CLIENT_ID" \
  --auth-flow USER_PASSWORD_AUTH \
  --auth-parameters USERNAME=$USERNAME,PASSWORD=$PASSWORD \
  --region $REGION | jq -r '.AuthenticationResult.AccessToken')

# Output the required values
echo "Pool id: $POOL_ID"
echo "Discovery URL: https://cognito-idp.$REGION.amazonaws.com/$POOL_ID/.well-known/openid-configuration"
echo "Client ID: $CLIENT_ID"
echo "Bearer Token: $BEARER_TOKEN"

Open a terminal window and set the following environment variables:

export REGION=us-east-1 // set your desired Region
export USERNAME=USER NAME
export PASSWORD=PASSWORD

Run the script using the command source setup_cognito.sh.

After running this script, note the following values for use in the deployment configuration:

Local testing with MCP inspector

The MCP Inspector is a visual tool for testing MCP servers. To use it, you need:

Install and run the MCP Inspector:

npx @modelcontextprotocol/inspector

This will:

To use the Inspector:

Remote testing with MCP inspector

You can also test your deployed server using the MCP Inspector: