STDIO to HTTP Proxy MCP Server Setup Guide

Overview

This guide walks you through setting up and deploying a PROXY AWS Model Context Protocol (MCP) server using AWS AgentCore.

What It Does

• Creates complete infrastructure for accessing AWS services via a standardized MCP interface
• Bridges the protocol gap between STDIO-based AWS MCP servers and HTTP-only MCP clients
• Provides an HTTP-to-STDIO proxy for seamless connectivity

Why It Matters

Some AWS MCP servers use STDIO transport, but services like Amazon QuickSight only support HTTP-based MCP clients. This implementation bridges that gap, enabling seamless integration across diverse application architectures. AWS MCP servers that already support HTTP transport can be used directly without this proxy mcp.

HL Architecture

┌─────────────┐    ┌──────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────┐
│ HTTP Client │───▶│AgentCore Gateway │───▶│AgentCore Runtime│───▶│ MCP Proxy Server│───▶│ AWS Services│
└─────────────┘    └──────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────┘
       │                      │                       │                       │                    │
       │                      │                       │                       │                    │
   ┌───▼────┐           ┌─────▼─────┐           ┌─────▼─────┐           ┌─────▼─────┐        ┌─────▼─────┐
   │Cognito │           │   MCP     │           │  OAuth2   │           │   STDIO   │        │CloudWatch │
   │  Auth  │           │ Protocol  │           │   Auth    │           │ Transport │        │           │
   └────────┘           └───────────┘           └───────────┘           └───────────┘        └───────────┘

Components Explained

1. HTTP Client

• Purpose: Any application that needs to access AWS services
• Protocol: HTTP/HTTPS with OAuth2 authentication
• Examples: Web applications, mobile apps, other microservices

2. AgentCore Gateway

• Purpose: Entry point for HTTP requests with authentication
• Features:
  • Cognito-based OAuth2 authentication
  • MCP protocol support
  • Request routing and validation
• Configuration: Created with specific IAM roles and Cognito integration

3. AgentCore Runtime

• Purpose: Hosts the MCP proxy server in AWS infrastructure
• Features:
  • Containerized deployment
  • Auto-scaling capabilities
  • CloudWatch integration for monitoring
• Deployment: Uses CodeBuild for container building and deployment

4. MCP Proxy Server

• Purpose: Bridges HTTP protocol to STDIO protocol
• Key Functions:
  • Protocol translation (HTTP ↔ STDIO)
  • AWS MCP server management
  • Tool discovery and invocation
• Implementation: Python-based using FastMCP framework

5. AWS MCP Server

• Purpose: Provides standardized access to AWS services
• Supported Services: CloudWatch, ECS, EC2, and more
• Protocol: STDIO-based communication

Setup Process Breakdown

Step 1: Environment Setup

# Configure AWS credentials and region
os.environ['AWS_ACCESS_KEY_ID'] = ''  # Optional if using IAM roles
os.environ['AWS_SECRET_ACCESS_KEY'] = ''  # Optional if using IAM roles
os.environ['AWS_DEFAULT_REGION'] = 'us-east-1'

What it does: Sets up the AWS environment for the deployment process.

Step 2: IAM Role Creation

agentcore_gateway_iam_role = helpers.create_agentcore_gateway_role("aws-mcpgateway")

What it does: Creates an IAM role with necessary permissions for the AgentCore Gateway to:

• Create and manage gateway resources
• Access other AWS services as needed
• Assume roles for cross-service communication

Step 3: Cognito Authentication Setup

Two separate Cognito user pools are created:

Gateway Pool

• Purpose: Authenticates incoming HTTP requests
• Scope: aws-agentcore-gateway-id/invoke
• Usage: Client applications use this for initial authentication

Runtime Pool

• Purpose: Authenticates gateway-to-runtime communication
• Scope: aws-agentcore-runtime-id/invoke
• Usage: Internal authentication between gateway and runtime

Step 4: Gateway Creation

gateway_client.create_gateway(
    name='aws-gateway-mcp-server',
    protocolType='MCP',
    authorizerType='CUSTOM_JWT'
)

What it does: Creates the main entry point that:

• Accepts HTTP requests
• Validates JWT tokens from Cognito
• Routes requests to appropriate targets
• Supports MCP protocol semantics

Step 5: MCP Proxy Server

The proxy server (aws_mcp_stdio_proxy_server.py) performs several critical functions:

Protocol Bridge

# HTTP → MCP → STDIO → AWS MCP Server
transport = StdioTransport(command="uvx", args=[AWS_MCP_SERVER])
proxy = FastMCP.as_proxy(ProxyClient(transport=transport))

Tool Management

@proxy.tool()
async def list_cloudwatch_tools():
    # Discovers available AWS service tools
    
@proxy.tool()
async def invoke_cloudwatch_tool(tool_name: str, arguments: dict):
    # Executes specific AWS service operations

Step 6: AgentCore Runtime Deployment

agentcore_runtime.configure(
    entrypoint="aws_mcp_stdio_proxy_server.py",
    protocol="MCP",
    authorizer_configuration=auth_config
)

What it does:

• Packages the proxy server into a container
• Deploys to AWS AgentCore infrastructure
• Configures authentication and networking
• Sets up monitoring and logging

Step 7: Gateway Target Connection

gateway_client.create_gateway_target(
    gatewayIdentifier=gatewayID,
    targetConfiguration={'mcp': {'mcpServer': {'endpoint': agent_url}}}
)

What it does: Connects the gateway to the runtime, enabling end-to-end communication flow.

Step 8: Test MCP Server Locally (Optional)

8.1: Start the Local MCP Proxy Server

Open a terminal and run the proxy server:

# Navigate to your project directory
cd /path/to/your/project

# Start the MCP proxy server locally
python aws_mcp_stdio_proxy_server.py

Expected Output:

Starting MCP server 'aws-mcp-http-stdio-proxy' with transport 'streamable-http' on  server.py:2055
                             http://0.0.0.0:8000/mcp                                                                           
INFO:     Started server process [78465]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

8.1: Start the Local MCP Proxy Server

Open a second terminal and run the test client:

# In a new terminal window
python aws_cw_mcp_client.py

Expected Output:

CloudWatch MCP Tools (13 found):
==================================================
1. list_cloudwatch_tools
   List CloudWatch tools from the MCP proxy
   Parameters: output_json
   ......

🎥 Demo

Watch the below demo to see the proxy in action! How this proxy helps in integrating Quick Suite with AWS CloudWatch MCP Server.

Quick Suite and AWS CloudWatch MCP Server

Authentication Flow

1. Client Authentication

Client → Cognito → JWT Token → Gateway

2. Internal Authentication

Gateway → OAuth2 Provider → Runtime

3. Service Authentication

Runtime → IAM Role → AWS Services

Key Configuration Parameters

Environment Variables

• AWS_PROFILE: AWS profile for local development
• AWS_MCP_SERVER: Target MCP server (default: CloudWatch)
• FASTMCP_LOG_LEVEL: Logging level for MCP operations

Cognito Configuration

• User Pools: Separate pools for gateway and runtime
• Scopes: Fine-grained permission control
• Client Credentials: Machine-to-machine authentication

AgentCore Configuration

• Protocol: MCP with semantic search support
• Memory: Short-term memory only (STM_ONLY)
• Deployment: CodeBuild-based container deployment

Monitoring and Troubleshooting

CloudWatch Logs

• Gateway logs: /aws/bedrock-agentcore/gateways/[gateway-id]
• Runtime logs: /aws/bedrock-agentcore/runtimes/[runtime-id]

Common Issues

1. Authentication Failures: Check Cognito configuration and token validity
2. Connection Timeouts: Verify network connectivity and security groups
3. Permission Errors: Review IAM roles and policies
4. Protocol Errors: Check MCP server compatibility and versions

Debugging Commands

# Tail runtime logs
aws logs tail /aws/bedrock-agentcore/runtimes/[runtime-id] --follow

# Check recent logs
aws logs tail /aws/bedrock-agentcore/runtimes/[runtime-id] --since 1h

Security Considerations

Authentication

• OAuth2 with JWT tokens
• Separate authentication domains for different components
• Token expiration and refresh mechanisms

Authorization

• IAM role-based access control
• Cognito scope-based permissions
• Principle of least privilege

Network Security

• HTTPS-only communication
• VPC-based deployment options
• Security group restrictions

Extending the Setup

Adding New AWS MCP Servers

1. This demonstration uses AWS CloudWatch MCP as an example but is applicable to any AWS MCP server. To switch servers, update the AWS_MCP_SERVER environment variable with the new MCP server configuration.
2. Update IAM permissions as needed.
3. Redeploy the runtime.

Custom MCP Tools

@proxy.tool()
async def custom_aws_operation(param1: str, param2: int):
    # Custom logic here
    return result

Conclusion

This AWS MCP proxy server provides a robust, enterprise-grade solution that transforms STDIO-based AWS MCP servers into HTTP-accessible services. Built on Amazon Bedrock AgentCore, it enables seamless integration with Amazon GenAI services like Amazon QuickSight—which natively supports HTTP-based MCP servers.

This example uses CloudWatch MCP, but feel free to try it with any STDIO-based AWS MCP server of your choice.

License

This project is licensed under the MIT No Attribution