Cost Explorer MCP Server

# Cost Explorer MCP Server - Agentcore Runtime Deployment This directory contains the Cost Explorer MCP Server configured for deployment to Amazon Bedrock Agentcore Runtime with streamable HTTP support on port 8000. ## 🏗️ Architecture - **Original**: STDIO-based MCP server for local development - **Converted**: Streamable HTTP server for Agentcore Runtime deployment - **Protocol**: MCP (Model Context Protocol) - **Transport**: Streamable HTTP on port 8000 - **Deployment**: Agentcore Runtime (no Agentcore memory) ## 📁 Project Structure ``` cost-explorer-agentcore-deployment/ ├── mcp_server.py # Main MCP server with streamable HTTP ├── requirements.txt # Python dependencies ├── __init__.py # Python package marker ├── awslabs/ # Cost Explorer implementation │ └── cost_explorer_mcp_server/ ├── deploy.py # Deployment automation script ├── test_mcp_client.py # Local testing client ├── test_remote_client.py # Remote testing client └── README.md # This file ``` ## 🚀 Quick Start ### 1. Prerequisites ```bash # Install required tools pip install bedrock-agentcore-starter-toolkit pip install mcp[cli] # Configure AWS credentials aws configure ``` ### 2. Test Locally First ```bash # Install dependencies pip install -r requirements.txt # Start the MCP server locally python mcp_server.py ``` In another terminal: ```bash # Test the local server python test_mcp_client.py ``` ### 3. Deploy to Agentcore Runtime ```bash # Run the deployment script python deploy.py ``` The script will: - Check prerequisites - Configure the deployment - Deploy to Agentcore Runtime - Save the Agent ARN to `agent_arn.txt` ### 4. Test Remote Deployment ```bash # Set environment variables export AGENT_ARN="your-agent-arn-from-deployment" export BEARER_TOKEN="your-oauth-token" # Test the deployed server python test_remote_client.py ``` ## 🔧 Manual Deployment Steps If you prefer manual deployment: ### 1. Configure Deployment ```bash agentcore configure -e mcp_server.py --protocol MCP ``` Follow the prompts: - **Protocol**: MCP - **Entry point**: mcp_server.py - **Authentication**: Choose OAuth or Cognito based on your needs ### 2. Deploy ```bash agentcore launch ``` ## 🔐 Authentication Setup ### Option 1: Cognito User Pool (Recommended) 1. Create a Cognito User Pool in AWS Console 2. Configure the user pool for your application 3. Use the provided credentials during deployment configuration ### Option 2: OAuth with Auth0 1. Set up Auth0 application with Dynamic Client Registration 2. Configure OAuth settings during deployment 3. Use Auth0 tokens for authentication ## 🧪 Testing ### Local Testing ```bash # Start server python mcp_server.py # Test in another terminal python test_mcp_client.py ``` ### Remote Testing ```bash # Set environment variables export AGENT_ARN="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/cost-explorer-xyz123" export BEARER_TOKEN="your-oauth-token" # Test deployed server python test_remote_client.py ``` ## 🛠️ Available Tools The Cost Explorer MCP Server provides these tools: 1. **get_today_date** - Get current date for relative queries 2. **get_dimension_values** - Get available values for dimensions (SERVICE, REGION, etc.) 3. **get_tag_values** - Get available tag values 4. **get_cost_and_usage** - Retrieve cost and usage data with filtering 5. **get_cost_and_usage_comparisons** - Compare costs between periods 6. **get_cost_comparison_drivers** - Analyze cost change drivers 7. **get_cost_forecast** - Generate cost forecasts ## 💰 Cost Considerations **Important**: Each AWS Cost Explorer API call costs $0.01. The server includes optimizations to minimize API calls, but be aware of potential charges when using the tools extensively. ## 🔍 Troubleshooting ### Local Server Issues ```bash # Check if port 8000 is available lsof -i :8000 # Check server logs python mcp_server.py ``` ### Deployment Issues ```bash # Check AWS credentials aws sts get-caller-identity # Verify agentcore CLI agentcore --version # Check deployment status agentcore status ``` ### Remote Connection Issues 1. Verify BEARER_TOKEN is valid and not expired 2. Check AGENT_ARN format and encoding 3. Ensure OAuth/Cognito is properly configured 4. Verify server deployment status ## 📚 References - [Agentcore Runtime MCP Documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp.html) - [Converting STDIO to Streamable HTTP](https://portkey.ai/docs/guides/converting-stdio-to-streamable-http) - [MCP Protocol Documentation](https://modelcontextprotocol.io/) - [AWS Cost Explorer API](https://docs.aws.amazon.com/cost-management/latest/userguide/ce-api.html) ## 🆘 Support For issues with: - **MCP Server**: Check the original cost-explorer-mcp-server documentation - **Agentcore Runtime**: Refer to AWS Bedrock Agentcore documentation - **Authentication**: Check your OAuth/Cognito configuration - **AWS Costs**: Review AWS Cost Explorer API pricing and usage