AWS MCP Demo
Deploy FastMCP server to AWS Bedrock AgentCore Runtime.
Ask AI about AWS MCP Demo
Powered by Claude Β· Grounded in docs
I know everything about AWS MCP Demo. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 logincredentials 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
-
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 -
Install dependencies:
cd mcp-server uv add fastmcp uv tool install bedrock-agentcore-starter-toolkit -
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 -
Fix ECR configuration: Step 3 creates
.bedrock_agentcore.yaml. Open.bedrock_agentcore.yamland changeecr_auto_createtotrue. This allows AgentCore to automatically create the Docker image repository during deployment. -
Deploy:
export AWS_PROFILE=process-<your-profile> agentcore deploy -
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/listshows theroll_d20tool,tools/callreturns dice results like[10, 20, 8] -
Cleanup when done:
export AWS_PROFILE=process-<your-profile> agentcore destroyNote: 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_processrunsaws configure export-credentialsto 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 logincreates 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:
- Modify server.py to use HTTP mode:
mcp.run(transport="http", port=8000) - Run:
uv run python server.py - Test with curl commands
- 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/listreturns theroll_d20tool with its description and schematools/callreturns 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:
-
"agentcore configure requires valid aws credentials"
- Solution: Use process credentials workaround (see Prerequisites)
-
"ECR repository not configured and auto-create not enabled"
- Solution: Edit
.bedrock_agentcore.yamland setecr_auto_create: true
- Solution: Edit
-
Docker build fails with "Unable to find lockfile at uv.lock"
- Solution: Use
uv syncnotuv sync --frozenin Dockerfile
- Solution: Use
-
Internal error when testing MCP calls
- Fixed: Updated server implementation with correct FastMCP configuration
- Use
host="0.0.0.0",stateless_http=True, andtransport="streamable-http" - MCP protocol calls now work correctly
- Prompt-based calls may still show errors but core functionality works
