Skip to content

README.md

Latest commit

 

History

History
358 lines (263 loc) · 11 KB

README.md

File metadata and controls

358 lines (263 loc) · 11 KB

Hosting MCP Server on AgentCore Runtime - CDK

Overview

This CDK stack deploys an MCP (Model Context Protocol) server on Amazon Bedrock AgentCore Runtime. It demonstrates how to host MCP tools on AgentCore Runtime using infrastructure as code, with automated deployment scripts for a streamlined experience.

The stack uses the Amazon Bedrock AgentCore Python SDK to wrap agent functions as an MCP server compatible with Amazon Bedrock AgentCore. It handles the MCP server details so you can focus on your agent's core functionality.

When hosting tools, the Amazon Bedrock AgentCore Python SDK implements the Stateless Streamable HTTP transport protocol with the MCP-Session-Id header for session isolation. Your MCP server will be hosted on port 8000 and provide one invocation path: the mcp-POST endpoint.

Tutorial Details

Information Details
Tutorial type Hosting Tools
Tool type MCP server
Tutorial components CDK, AgentCore Runtime, MCP server
Tutorial vertical Cross-vertical
Example complexity Easy
SDK used Amazon BedrockAgentCore Python SDK and MCP Client

Architecture

MCP Server AgentCore Runtime Architecture

This CDK stack deploys a simple MCP server with 3 tools: add_numbers, multiply_numbers, and greet_user.

The architecture consists of:

  • User/MCP Client: Sends requests to the MCP server with JWT authentication
  • Amazon Cognito: Provides JWT-based authentication
    • User Pool with pre-created test user (testuser/MyPassword123!)
    • User Pool Client for application access
  • AWS CodeBuild: Builds the ARM64 Docker container image with the MCP server
  • Amazon ECR Repository: Stores the container image
  • AgentCore Runtime: Hosts the MCP Server
    • MCP Server: Exposes three tools via HTTP transport
      • add_numbers: Adds two numbers
      • multiply_numbers: Multiplies two numbers
      • greet_user: Greets a user by name
    • Validates JWT tokens from Cognito
    • Processes MCP tool invocations
  • IAM Roles:
    • IAM role for CodeBuild (builds and pushes images)
    • IAM role for AgentCore Runtime (runtime permissions)

Key Features

  • Complete Infrastructure as Code - Full CDK implementation
  • Secure by Default - JWT authentication with Cognito
  • Automated Build - CodeBuild creates ARM64 Docker images
  • Easy Testing - Automated test script included
  • Simple Cleanup - One command removes all resources

What Gets Deployed

The CDK stack creates:

  • Amazon ECR Repository - Stores the MCP server Docker image
  • AWS CodeBuild Project - Builds ARM64 Docker image automatically
  • Amazon Cognito User Pool - JWT authentication
  • Cognito User Pool Client - Application client configuration
  • Cognito User - Pre-created test user (testuser/MyPassword123!)
  • IAM Roles - Least-privilege permissions for all services
  • Lambda Functions - Custom resource automation
  • Amazon Bedrock AgentCore Runtime - Hosts the MCP server

MCP Server Tools:

  • add_numbers - Adds two numbers together
  • multiply_numbers - Multiplies two numbers
  • greet_user - Greets a user by name

Table of Contents

Overview

This CDK stack creates an MCP server with JWT authentication using Amazon Cognito. The MCP server provides three tools: add_numbers, multiply_numbers, and greet_user.

Key Features

  • Complete Infrastructure as Code - Full CDK implementation
  • Secure by Default - JWT authentication with Cognito
  • Automated Build - CodeBuild creates ARM64 Docker images
  • Easy Testing - Automated test script included
  • Simple Cleanup - One command removes all resources

Architecture

The architecture consists of:

  • User/MCP Client: Sends requests to the MCP server with JWT authentication
  • Amazon Cognito: Provides JWT-based authentication
    • User Pool with pre-created test user (testuser/MyPassword123!)
    • User Pool Client for application access
  • AWS CodeBuild: Builds the ARM64 Docker container image with the MCP server
  • Amazon ECR Repository: Stores the container image
  • AgentCore Runtime: Hosts the MCP Server
    • MCP Server: Exposes three tools via HTTP transport
      • add_numbers: Adds two numbers
      • multiply_numbers: Multiplies two numbers
      • greet_user: Greets a user by name
    • Validates JWT tokens from Cognito
    • Processes MCP tool invocations
  • IAM Roles:
    • IAM role for CodeBuild (builds and pushes images)
    • IAM role for AgentCore Runtime (runtime permissions)

What Gets Deployed

The CDK stack creates:

  • Amazon ECR Repository - Stores the MCP server Docker image
  • AWS CodeBuild Project - Builds ARM64 Docker image automatically
  • Amazon Cognito User Pool - JWT authentication
  • Cognito User Pool Client - Application client configuration
  • Cognito User - Pre-created test user (testuser/MyPassword123!)
  • IAM Roles - Least-privilege permissions for all services
  • Lambda Functions - Custom resource automation
  • Amazon Bedrock AgentCore Runtime - Hosts the MCP server

MCP Server Tools:

  • add_numbers - Adds two numbers together
  • multiply_numbers - Multiplies two numbers
  • greet_user - Greets a user by name

Prerequisites

  • AWS CLI configured with appropriate credentials
  • AWS account with permissions to create:
    • CloudFormation stacks
    • ECR repositories
    • CodeBuild projects
    • Cognito User Pools
    • IAM roles and policies
    • Lambda functions
    • Bedrock AgentCore Runtime
  • Python 3.10+ and AWS CDK v2 installed
  • CDK version 2.220.0 or later (for BedrockAgentCore support)

Deployment

CDK vs CloudFormation

This is the CDK version of the MCP server AgentCore runtime. If you prefer CloudFormation, see the CloudFormation version.

Option 1: Quick Deploy (Recommended)

# Install dependencies
pip install -r requirements.txt

# Bootstrap CDK (first time only)
cdk bootstrap

# Deploy
cdk deploy

Option 2: Step by Step

# 1. Create and activate Python virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Bootstrap CDK in your account/region (first time only)
cdk bootstrap

# 4. Synthesize the CloudFormation template (optional)
cdk synth

# 5. Deploy the stack
cdk deploy --require-approval never

# 6. Get outputs
cdk list

Deployment Time

The deployment takes approximately 10-15 minutes and includes:

  • Creating all AWS resources
  • Building the Docker image
  • Pushing to ECR
  • Starting the AgentCore Runtime

Testing

1. Get Authentication Token

First, get a JWT token from Cognito:

# Get the Cognito User Pool Client ID from CDK outputs
CLIENT_ID=$(aws cloudformation describe-stacks \
  --stack-name MCPServerDemo \
  --region us-east-1 \
  --query 'Stacks[0].Outputs[?OutputKey==`CognitoUserPoolClientId`].OutputValue' \
  --output text)

# Get authentication token
python get_token.py $CLIENT_ID testuser MyPassword123! us-east-1

This will output a JWT token. Copy the token for the next step.

2. Test the MCP Server

# Get the MCP Server Runtime ARN
RUNTIME_ARN=$(aws cloudformation describe-stacks \
  --stack-name MCPServerDemo \
  --region us-east-1 \
  --query 'Stacks[0].Outputs[?OutputKey==`MCPServerRuntimeArn`].OutputValue' \
  --output text)

# Test the MCP server (replace YOUR_JWT_TOKEN with the token from step 1)
python test_mcp_server.py $RUNTIME_ARN YOUR_JWT_TOKEN us-east-1

This will:

  • Connect to the MCP server
  • List available tools
  • Test all three MCP tools
  • Display the results

Expected Output

🔄 Initializing MCP session...
✓ MCP session initialized

🔄 Listing available tools...

📋 Available MCP Tools:
==================================================
🔧 add_numbers: Add two numbers together
🔧 multiply_numbers: Multiply two numbers together
🔧 greet_user: Greet a user by name

🧪 Testing MCP Tools:
==================================================

➕ Testing add_numbers(5, 3)...
   Result: 8

✖️  Testing multiply_numbers(4, 7)...
   Result: 28

👋 Testing greet_user('Alice')...
   Result: Hello, Alice! Nice to meet you.

✅ MCP tool testing completed!

Cleanup

Using CDK (Recommended)

cdk destroy

Using AWS CLI

aws cloudformation delete-stack \
  --stack-name MCPServerDemo \
  --region us-east-1

# Wait for deletion to complete
aws cloudformation wait stack-delete-complete \
  --stack-name MCPServerDemo \
  --region us-east-1

Troubleshooting

CDK Bootstrap Required

If you see bootstrap errors:

cdk bootstrap aws://ACCOUNT-NUMBER/REGION

Permission Issues

Ensure your IAM user/role has:

  • CDKToolkit permissions or equivalent
  • Permissions to create all resources in the stack
  • iam:PassRole for service roles

Python Dependencies

Install dependencies in the project directory:

pip install -r requirements.txt

For testing, you may need additional packages:

pip install boto3 mcp

Authentication Issues

If authentication fails:

  • Verify the Cognito User Pool Client ID is correct
  • Ensure you're using the correct region
  • Check that the user exists and password is correct
  • Verify USER_PASSWORD_AUTH is enabled for the client

Build Failures

Check CodeBuild logs in the AWS Console:

  1. Go to CodeBuild console
  2. Find the build project (name contains "mcp-server-build")
  3. Check build history and logs

Cost Estimate

Monthly Cost Breakdown (us-east-1)

Service Usage Monthly Cost
AgentCore Runtime 1 runtime, minimal usage ~$5-10
ECR Repository 1 repository, <1GB storage ~$0.10
CodeBuild Occasional builds ~$1-2
Lambda Custom resource executions ~$0.01
Cognito User Pool 1 user pool, minimal usage ~$0.01
CloudWatch Logs Agent logs ~$0.50

Estimated Total: ~$7-13/month

Cost Optimization Tips

  • Delete when not in use: Use cdk destroy to remove all resources
  • Monitor usage: Set up CloudWatch billing alarms
  • Optimize builds: Only rebuild when code changes

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.