MCP Server Deployment to AWS AgentCore Runtime

Following the tutorial: From Local MCP Server to AWS Deployment in Two Commands

Note: This implementation uses aws login credentials instead of traditional long-term AWS credentials. Some additional steps are included to handle the credential compatibility requirements with AgentCore toolkit.

Note: Replace <your-profile> with your actual AWS profile name before running commands.

🚀 Quick Start (If You Cloned This Repo)

If you cloned this repository and just want to deploy the MCP server, follow these minimal steps:

Prerequisites

• AWS CLI 2.32.0+
• Python 3.10+ with uv package manager
• Valid AWS credentials via aws login

Deploy in 6 Steps

1. Set up process credentials (one-time setup):

   aws configure set credential_process "aws configure export-credentials --profile <your-profile> --format process" --profile process-<your-profile>
   aws sts get-caller-identity --profile process-<your-profile>  # verify it works
   

2. Install dependencies:

   cd mcp-server
   uv add fastmcp
   uv tool install bedrock-agentcore-starter-toolkit
   

3. Configure and deploy:

   export AWS_PROFILE=process-<your-profile>
   agentcore configure --create --entrypoint server.py --name dice_mcp_server --deployment-type container --protocol MCP --non-interactive
   

4. Fix ECR configuration: Step 3 creates .bedrock_agentcore.yaml. Open .bedrock_agentcore.yaml and change ecr_auto_create to true. This allows AgentCore to automatically create the Docker image repository during deployment.

5. Deploy:

   export AWS_PROFILE=process-<your-profile>
   agentcore deploy
   

6. Test (verify MCP server functionality):

   export AWS_PROFILE=process-<your-profile>
   # List available tools
   agentcore invoke '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
   
   # Call the roll_d20 tool
   agentcore invoke '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"roll_d20","arguments":{"number_of_dice":3}}}'
   

   Expected: tools/list shows the roll_d20 tool, tools/call returns dice results like [10, 20, 8]

7. Cleanup when done:

   export AWS_PROFILE=process-<your-profile>
   agentcore destroy
   

   Note: You may need to manually delete leftover ECR repositories and CloudWatch log groups.

---

📖 Full Tutorial (Building From Scratch)

If you want to understand the complete process or build from scratch, follow the detailed steps below:

Prerequisites

• AWS CLI 2.32.0+
• Python 3.10+ with uv package manager
• Valid AWS credentials via aws login

Important: Credential Setup for AgentCore Compatibility

Issue: The AgentCore toolkit cannot directly use aws login credentials, even though AWS CLI works fine.

Solution: Create a process credentials profile that acts as a "bridge":

# Step 1: Create process credentials profile (one-time setup)
aws configure set credential_process "aws configure export-credentials --profile <your-profile> --format process" --profile process-<your-profile>

# Step 2: Verify it works
aws sts get-caller-identity --profile process-<your-profile>

# Step 3: Use this profile for all agentcore commands
export AWS_PROFILE=process-<your-profile>

What this does:

• process-<your-profile> is a wrapper profile that converts your login credentials to a format agentcore can understand
• The credential_process runs aws configure export-credentials to get your login credentials in the right format
• export AWS_PROFILE=process-<your-profile> tells all AWS tools in that terminal to use the wrapper profile

Why this is needed:

• aws login creates temporary credentials using a newer credential provider
• Some tools (like agentcore) don't support this provider yet
• Process credentials is AWS's recommended workaround for this compatibility issue
• This is documented in the AWS CLI documentation

Step 1: Create Your MCP Server

Create the project structure:

uv init --bare mcp-server
cd mcp-server
uv add fastmcp

Create server.py

Create mcp-server/server.py with this exact content:

import random
from fastmcp import FastMCP

# Create the MCP server with AgentCore Runtime configuration
mcp = FastMCP("Dice Rolling Server", host="0.0.0.0", stateless_http=True)

@mcp.tool()
def roll_d20(number_of_dice: int = 1) -> list[int]:
    """Roll a 20-sided die multiple times.
    
    Args:
        number_of_dice: Number of dice to roll (default: 1)
        
    Returns:
        List of dice roll results
    """
    return [random.randint(1, 20) for _ in range(number_of_dice)]

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

Step 2: Test Locally (Optional)

Note: Local testing requires HTTP mode, but AgentCore uses stdio mode. You can skip this step.

If you want to test locally:

1. Modify server.py to use HTTP mode: mcp.run(transport="http", port=8000)
2. Run: uv run python server.py
3. Test with curl commands
4. Important: Change back to mcp.run() before deploying to AgentCore

Step 3: Install AgentCore Toolkit

uv tool install bedrock-agentcore-starter-toolkit

Step 4: Configure for AgentCore Runtime

export AWS_PROFILE=process-<your-profile>

Configure AgentCore with the correct parameters:

agentcore configure --create --entrypoint server.py --name dice_mcp_server --deployment-type container --protocol MCP --non-interactive

Step 5: Create Dockerfile for Container Build

For the container deployment, create a Dockerfile:

Create mcp-server/Dockerfile:

FROM python:3.12-slim

WORKDIR /app

# Copy project files
COPY pyproject.toml ./
COPY server.py ./

# Install uv and dependencies
RUN pip install uv
RUN uv sync

# Expose port (though AgentCore uses stdio)
EXPOSE 8000

# Run the MCP server
CMD ["uv", "run", "python", "server.py"]

Important: Use uv sync NOT uv sync --frozen (the frozen flag requires a lockfile that doesn't exist)

Step 6: Fix ECR Configuration

The configuration may not enable ECR auto-creation. Edit .bedrock_agentcore.yaml and change:

ecr_auto_create: false

to:

ecr_auto_create: true

Step 7: Deploy to AgentCore Runtime

export AWS_PROFILE=process-<your-profile>
agentcore deploy

What happens:

• Creates memory resource (takes 2-3 minutes)
• Builds container in CodeBuild (takes 1-2 minutes)
• Deploys to AgentCore Runtime
• Sets up observability (CloudWatch Logs + X-Ray)

Expected output:

🎉 CodeBuild completed successfully
Agent created/updated: arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/dice_mcp_server-XXXXX
✅ Deployment Success

Step 8: Test Deployed Server

export AWS_PROFILE=process-<your-profile>

# List available tools
agentcore invoke '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call roll_d20 tool
agentcore invoke '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"roll_d20","arguments":{"number_of_dice":3}}}'

Expected Results:

• tools/list returns the roll_d20 tool with its description and schema
• tools/call returns actual dice roll results like [10, 20, 8]

Step 9: Cleanup (Important!)

Always clean up resources to avoid charges:

export AWS_PROFILE=process-<your-profile>
agentcore destroy

What gets deleted:

• AgentCore runtime
• ECR repository and images
• CodeBuild project
• S3 artifacts
• Memory resources
• IAM roles
• Configuration files

Troubleshooting

Common Issues:

1. "agentcore configure requires valid aws credentials"

   • Solution: Use process credentials workaround (see Prerequisites)

2. "ECR repository not configured and auto-create not enabled"

   • Solution: Edit .bedrock_agentcore.yaml and set ecr_auto_create: true

3. Docker build fails with "Unable to find lockfile at uv.lock"

   • Solution: Use uv sync not uv sync --frozen in Dockerfile

4. Internal error when testing MCP calls

   • Fixed: Updated server implementation with correct FastMCP configuration
   • Use host="0.0.0.0", stateless_http=True, and transport="streamable-http"
   • MCP protocol calls now work correctly
   • Prompt-based calls may still show errors but core functionality works