MCP AWS Test Project

A Model Context Protocol (MCP) server implementation designed to run on AWS Bedrock AgentCore with Cognito authentication.

Overview

This project implements an MCP server using FastMCP that provides simple tools for mathematical operations and user greetings. The server is containerized and deployed to AWS Bedrock AgentCore with JWT authentication via AWS Cognito.

Project Structure

mcp-aws-test/
├── mcp_server/                 # Main server package
│   ├── __init__.py
│   ├── server.py              # FastMCP server configuration
│   └── tools.py               # MCP tools implementation
├── my_mcp_server.py           # Main entry point
├── mcp_client_remote.py       # Remote client for testing
├── setup_cognito.sh           # Cognito setup script
├── Dockerfile                 # Container configuration
├── requirements.txt           # Python dependencies
├── .bedrock_agentcore.yaml    # AWS Bedrock AgentCore configuration
├── .env                       # Environment variables (gitignored)
├── .dockerignore             # Docker ignore rules
└── .gitignore                # Git ignore rules

Features

Available Tools

The MCP server provides the following tools:

1. add_numbers - Adds two integers

   • Parameters: a: int, b: int
   • Returns: int (sum of a and b)

2. greet_user - Greets a user in Spanish

   • Parameters: name: str
   • Returns: str (greeting message)

Setup and Deployment

Prerequisites

• Python 3.12+
• Docker
• AWS CLI configured
• jq (for JSON parsing in setup script)

1. Install Dependencies

pip install -r requirements.txt

2. AWS Cognito Setup

Run the Cognito setup script to create the required authentication infrastructure:

chmod +x setup_cognito.sh
./setup_cognito.sh

This script will:

• Create a Cognito User Pool
• Create an App Client
• Create a test user with credentials
• Generate a Bearer token for authentication

3. Environment Configuration

Create a .env file with the following variables:

AGENT_ARN="your-agent-arn"
BEARER_TOKEN="your-bearer-token"

4. Docker Build and Run

# Build the container
docker build -t mcp-aws-test .

# Run locally for testing
docker run -p 8080:8080 -p 8000:8000 mcp-aws-test

Configuration Files

.bedrock_agentcore.yaml

Contains the AWS Bedrock AgentCore configuration including:

• Agent definition and runtime settings
• AWS execution roles and ECR repository
• Network and protocol configuration
• Cognito JWT authentication setup

Dockerfile

Multi-stage Docker build that:

• Uses Python 3.12 slim base image
• Installs dependencies including OpenTelemetry
• Sets up non-root user for security
• Exposes ports 8080 and 8000
• Runs with OpenTelemetry instrumentation

Usage

Running the Server

python my_mcp_server.py

The server will start on 0.0.0.0 with HTTP transport.

Testing with Remote Client

Use the included remote client to test the deployed server:

python mcp_client_remote.py

This will:

1. Read environment variables for Agent ARN and Bearer token
2. Connect to the AWS Bedrock AgentCore endpoint
3. List available tools
4. Display the results

Authentication

The project uses AWS Cognito for JWT-based authentication:

• Discovery URL: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_E7EAxr9SP/.well-known/openid-configuration
• Test User: testuser / ManoloCDK
• Client ID: Configured in the Cognito setup

AWS Resources

Required IAM Roles

• Execution Role: AmazonBedrockAgentCoreSDKRuntime-us-east-1-cb7bbfb8e9
• CodeBuild Role: AmazonBedrockAgentCoreSDKCodeBuild-us-east-1-cb7bbfb8e9

AWS Services Used

• AWS Bedrock AgentCore: Runtime environment
• Amazon ECR: Container registry
• AWS CodeBuild: Build pipeline
• Amazon Cognito: Authentication provider
• AWS CloudWatch: Observability (enabled)

Development

Adding New Tools

To add new tools, modify mcp_server/tools.py:

@mcp.tool()
def your_new_tool(param: str) -> str:
    """Your tool description"""
    return f"Processed: {param}"

Local Development

# Install in development mode
pip install -e .

# Run server locally
python my_mcp_server.py

Environment Variables

• AGENT_ARN: AWS Bedrock AgentCore runtime ARN
• BEARER_TOKEN: Cognito JWT access token
• AWS_REGION: AWS region (default: us-west-2)
• DOCKER_CONTAINER: Flag indicating Docker environment

Security Notes

• The .env file is gitignored and contains sensitive tokens
• Bearer tokens have expiration times and need periodic refresh
• The container runs as non-root user bedrock_agentcore
• Network mode is set to PUBLIC in the configuration

Troubleshooting

Common Issues

1. Authentication Errors: Ensure Bearer token is valid and not expired
2. Connection Issues: Verify Agent ARN and endpoint URLs
3. Build Failures: Check Docker daemon and ECR permissions

Logs and Monitoring

OpenTelemetry instrumentation is enabled for observability. Check CloudWatch logs for detailed runtime information.

License

This project is for testing and development purposes.