FastMCP Math Operations Server on AWS Bedrock AgentCore

A production-ready implementation of mathematical operations using FastMCP (Model Context Protocol) deployed on AWS Bedrock AgentCore Runtime. This server provides natural language processing for mathematical calculations with conversational memory and context awareness, leveraging the full power of AWS Bedrock's managed agent infrastructure.

What is AWS Bedrock AgentCore?

AWS Bedrock AgentCore is a managed runtime environment for deploying and running agent-based applications at scale. This project leverages AgentCore to provide:

• Managed Infrastructure: Automatic scaling, monitoring, and health checks
• Memory Management: Built-in conversation history and session state via AgentCore Memory
• Seamless Deployment: One-command deployment from local development to AWS
• Enterprise Security: IAM-based authentication and Cognito integration
• Cost Optimization: Pay-per-use pricing with automatic resource scaling

By deploying on AgentCore, this FastMCP server benefits from AWS-managed operations, eliminating the need for manual infrastructure management while providing production-grade reliability and performance.

Key Features

AgentCore-Powered Capabilities

• Managed Deployment: Deploy directly to AWS Bedrock AgentCore Runtime with automatic scaling
• Conversational Memory: Built-in session management via AgentCore Memory - maintains context across conversations
• Zero Infrastructure Management: No need to manage servers, containers, or orchestration
• Production Monitoring: Integrated CloudWatch logging and health checks

Application Features

• Natural Language Processing: Calculate math operations from plain English text
• Multiple Operations: Support for addition and multiplication with LLM-powered parsing
• Context-Aware Calculations: Follow-up operations that remember previous results
• Type Safety: Runtime type checking with beartype for robust error handling
• Comprehensive Testing: Unit and integration tests with pytest
• Local Development: Test locally before deploying to AgentCore

Quick Start

Prerequisites

• Python 3.12+
• uv package manager
• AWS credentials (for AWS deployment)
• Docker (optional, for containerized deployment)

Installation

# Install dependencies
make install

# Or manually with uv
uv sync --all-extras --dev

Environment Setup

Create a .env file with required configuration:

# AWS Configuration
AWS_PROFILE=your-profile
AWS_REGION=ap-southeast-2
AWS_DEFAULT_REGION=ap-southeast-2

# Bedrock Configuration
BEDROCK_MODEL_ID=anthropic.claude-3-sonnet-20240229-v1:0
MEMORY_ID=your-memory-id

# MCP Server Configuration (optional)
MCP_HOST=0.0.0.0
MCP_PORT=3000

Running Locally

# Start the server
make run

# Server will be available at http://0.0.0.0:3000/mcp

Testing

# Run all tests
make test

# Run tests with coverage
make test-cov

# Test the running server locally
make agentcore-local-test

# Or use alternative AgentCore commands
make agentcore-local-run   # Start server
make agentcore-stop-local  # Stop server

Architecture

Components

src/
├── agents/                  # Mathematical operation agents
│   ├── addition.py         # Addition operations
│   └── multiplication.py   # Multiplication operations
├── shared/                 # Shared utilities
│   └── number_converter.py # Text-to-number conversion
└── agentcore_runtime/      # MCP server runtime
    ├── server.py           # Main server implementation
    └── auth.py             # Authentication handling

Key Technologies

AWS Bedrock AgentCore Integration

• bedrock-agentcore: Python SDK for AgentCore Runtime deployment and management
• bedrock-agentcore-starter-toolkit: Templates and utilities for AgentCore projects
• AgentCore Memory: Managed conversation history and session state storage
• AgentCore Runtime: Serverless execution environment with automatic scaling

Core Framework

• FastMCP: High-performance Model Context Protocol implementation
• AWS Bedrock: LLM inference using Claude 3 Sonnet for natural language understanding
• Strands Agents: Structured agent framework for building composable AI operations
• Pydantic: Data validation and settings management
• Beartype: Runtime type checking for type safety

Usage Examples

Basic Calculations

# Addition
"two plus three"        → 5
"add 10 and 20"        → 30
"sum of 5, 10, and 15" → 30

# Multiplication
"five times three"      → 15
"multiply 4 by 6"      → 24
"product of 7 and 8"   → 56

Conversational Context

# Turn 1
"two plus two"         → 4

# Turn 2 (with context)
"add three to that"    → 7  # Remembers previous result

Available Tools

The server exposes the following MCP tools:

• calculate(text, actor_id?, session_id?) - Natural language math operations
• add_numbers(a, b, actor_id?) - Direct addition
• multiply_numbers(a, b, actor_id?) - Direct multiplication
• get_calculation_history(actor_id, k?) - Retrieve conversation history
• get_session_summary(actor_id) - Get session summary
• list_operations() - List available operations

Development

Code Quality

# Format code
make format

# Run linting
make lint

# Fix linting issues
make lint-fix

# Run all checks
make check

Development Workflow

# Complete development cycle
make dev

# This runs:
# 1. Code formatting
# 2. Linting fixes
# 3. All tests

Docker Deployment

Build and Run

# Build Docker image
make docker-build

# Start services
make docker-up

# View logs
make docker-logs

# Stop services
make docker-down

Test Docker Deployment

make docker-test

AWS Bedrock AgentCore Deployment

This project is specifically designed for AWS Bedrock AgentCore Runtime, which provides:

What AgentCore Provides

1. Managed Runtime Environment: No need to configure Lambda, API Gateway, or ECS
2. Built-in Memory Management: Conversation history automatically persisted and retrieved
3. Auto-scaling: Handles traffic spikes without manual intervention
4. Health Monitoring: CloudWatch integration for logs and metrics
5. ECR Integration: Automatic Docker image management
6. Session Management: Built-in session ID generation and tracking

How bedrock-agentcore Enables This Project

The bedrock-agentcore package provides:

• BedrockAgentCoreApp: Main application wrapper for AgentCore compatibility
• MemoryClient: Direct integration with AgentCore Memory for conversation persistence
• Deployment Tools: CLI commands to configure, deploy, and manage AgentCore applications
• Session Context: Automatic session ID extraction and management

Prerequisites

1. AWS account with Bedrock AgentCore access
2. Valid AWS SSO credentials with appropriate permissions
3. Bedrock model access enabled (Claude 3 Sonnet)
4. AWS CLI configured with your profile

Deployment Steps

# Full deployment (recommended)
make agentcore-deploy

# Or step by step:
# 1. Configure deployment
make agentcore-configure

# 2. Launch to AWS
make agentcore-launch

# 3. Check status
make agentcore-status

# 4. Test remote deployment
make agentcore-test-remote

What Happens During Deployment

When you deploy to AgentCore, the system:

1. Packages Your Application: Bundles FastMCP server with AgentCore SDK
2. Builds Docker Image: Creates container with all dependencies
3. Pushes to ECR: Uploads image to AWS Elastic Container Registry
4. Creates AgentCore Runtime: Provisions managed runtime environment
5. Configures Memory: Sets up AgentCore Memory with your MEMORY_ID
6. Exposes MCP Endpoint: Makes tools available via streamable-http

Deployment Configuration

The deployment uses AWS Bedrock AgentCore Runtime with:

• Protocol: MCP (Model Context Protocol) - standardized agent communication
• Transport: streamable-http - for real-time streaming responses
• Container: ECR-hosted Docker image with bedrock-agentcore integration
• Memory: AgentCore Memory for persistent conversation history
• Runtime: Managed execution environment with auto-scaling
• Authentication: AWS Cognito (optional) or IAM-based access

Cleanup

# Destroy AgentCore deployment
make agentcore-destroy

# Clean up Cognito resources
make agentcore-cleanup-cognito

# Complete cleanup
make agentcore-cleanup-all

Testing

Unit Tests

# Run all tests
make test

# Or manually with uv
uv run pytest tests/ -v

# With coverage report
make test-cov

# Or manually with uv
uv run pytest tests/ --cov=src --cov-report=term-missing --cov-report=html

Integration Tests

# Test local server
uv run python scripts/test_mcp_client.py

# Test remote AWS deployment
uv run python scripts/test_jwt_remote.py

Project Structure

.
├── src/                    # Source code
├── tests/                  # Test suite
├── scripts/                # Utility scripts
├── docs/                   # Documentation
├── docker/                 # Docker configurations
├── config/                 # Configuration files
├── pyproject.toml         # Project dependencies
├── Makefile               # Development commands
└── README.md              # This file

Troubleshooting

Common Issues

Server won't start

• Verify AWS credentials: aws sts get-caller-identity
• Check MEMORY_ID is set in .env
• Ensure port 3000 is available

AWS deployment fails

• Run validation: uv run python scripts/validate_before_deploy.py
• Verify AWS permissions for ECR, Lambda, and AgentCore
• Check AWS region matches MEMORY_ID region

Tests failing

• Ensure server is running: make run
• Check AWS credentials are valid
• Verify dependencies: make install

Logs

# Local logs
tail -f logs/agentcore_server.log

# Docker logs
make docker-logs

# AWS logs
aws logs tail /aws/bedrock-agentcore/math-operations-mcp --follow

Performance with AgentCore

Response Characteristics

• Response Time: < 2s for typical calculations (including LLM inference)
• Concurrency: Unlimited concurrent sessions via AgentCore auto-scaling
• Memory Access: Sub-100ms retrieval of conversation history from AgentCore Memory
• Scalability: Automatic scaling from 0 to thousands of requests per second

AgentCore Advantages

• Cold Start Optimization: AgentCore minimizes cold start latency
• Memory Management: Automatic caching and retrieval of session state
• Resource Efficiency: Pay only for actual compute time, no idle costs
• Global Availability: Deploy to multiple AWS regions for low latency

Security

• Runtime type validation with beartype
• Input sanitization for all tools
• AWS IAM-based authentication
• Optional Cognito integration for user management
• Secrets stored in environment variables

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run make dev to validate
5. Submit a pull request

License

See LICENSE file for details.

Support

For issues and questions:

• Check the troubleshooting section above
• Review documentation in docs/guides/
• Examine test examples in tests/
• Review Makefile for available commands: make help