Sigv4 Proxy
An MCP proxy for servers that require AWS sigv4 or sigv4a authentication.
Ask AI about Sigv4 Proxy
Powered by Claude Β· Grounded in docs
I know everything about Sigv4 Proxy. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
AWS SigV4 Signing Proxy MCP Server
An MCP (Model Context Protocol) server that acts as a transparent proxy, forwarding MCP protocol messages to a target MCP server that requires IAM authentication. The proxy automatically signs requests with AWS Signature Version 4 (SigV4) or Signature Version 4A (SigV4a).
Overview
This proxy enables MCP clients to connect to IAM-authenticated MCP servers without implementing signing logic themselves. It sits between the client and the target server, transparently forwarding messages while adding AWS authentication.
βββββββββββββββ ββββββββββββββββββββββββββββ βββββββββββββββββββ
β β stdio β β HTTPS β β
β MCP Client ββββββββββΆβ Signing Proxy ββββββββββΆβ Target MCP β
β β β (mcp.Server) β +SigV4 β Server (IAM) β
β βββββββββββ βββββββββββ β
βββββββββββββββ ββββββββββββββββββββββββββββ βββββββββββββββββββ
Features
- Transparent Proxying: Forwards all MCP protocol messages without modification
- AWS SigV4 Signing: Automatically signs HTTP requests with AWS credentials
- SigV4a Support: Multi-region signing for global services
- Standard Credential Chain: Uses AWS SDK's default credential provider
- Profile Support: Can use named AWS credential profiles
- Session Token Support: Handles temporary credentials with session tokens
- Server-Sent Events: Optional SSE support for streaming responses
- Request Timeout: Configurable timeout for HTTP requests to target server
- Custom Headers: Add custom headers to proxied requests
- Graceful Shutdown: Handles SIGINT/SIGTERM signals for clean shutdown
- Structured Logging: Provides detailed logging for debugging and monitoring
Quick Start
Installation
From Source
git clone https://github.com/nisimpson/mcp-sigv4-proxy.git
cd mcp-sigv4-proxy
go build -o sigv4-proxy ./sigv4-proxy
Using Go Install
go install github.com/nisimpson/mcp-sigv4-proxy@latest
Basic Usage
-
Set up AWS credentials (see AWS Credentials section)
-
Configure the proxy using environment variables:
export MCP_TARGET_URL=https://your-mcp-server.execute-api.us-east-1.amazonaws.com
export AWS_REGION=us-east-1
export AWS_SERVICE_NAME=execute-api
- Run the proxy:
sigv4-proxy
The proxy will start and listen for MCP protocol messages on stdin/stdout.
Configuration
Configuration Options
The proxy can be configured via command-line flags or environment variables. Command-line flags take precedence over environment variables.
| Parameter | Flag | Environment Variable | Required | Default | Description |
|---|---|---|---|---|---|
| Target URL | --target-url | MCP_TARGET_URL | Yes | - | The HTTPS endpoint of the target MCP server |
| Region | --region | AWS_REGION | Yes | - | AWS region for signing (e.g., us-east-1) |
| Service Name | --service-name | AWS_SERVICE_NAME | Yes | - | AWS service name for signing (e.g., execute-api) |
| Signature Version | --sig-version | AWS_SIG_VERSION | No | v4 | Signature version: v4 or v4a |
| Profile | --profile | AWS_PROFILE | No | default | AWS credential profile name |
| Enable SSE | --sse | MCP_ENABLE_SSE | No | false | Enable Server-Sent Events for streaming responses |
| Timeout | --timeout | MCP_TIMEOUT | No | No timeout | Request timeout duration (e.g., 30s, 1m) |
| Headers | --headers | MCP_HEADERS | No | - | Comma-delimited custom headers (format: key=value,key2=value2) |
Configuration Examples
Example 1: API Gateway MCP Server
sigv4-proxy \
--target-url https://abc123.execute-api.us-east-1.amazonaws.com \
--region us-east-1 \
--service-name execute-api
Example 2: Using Environment Variables
export MCP_TARGET_URL=https://abc123.execute-api.us-west-2.amazonaws.com
export AWS_REGION=us-west-2
export AWS_SERVICE_NAME=execute-api
export AWS_SIG_VERSION=v4
sigv4-proxy
Example 3: Multi-Region with SigV4a
sigv4-proxy \
--target-url https://global-mcp-server.example.com \
--region us-east-1 \
--service-name execute-api \
--sig-version v4a
Example 4: Using a Named AWS Profile
sigv4-proxy \
--target-url https://abc123.execute-api.us-east-1.amazonaws.com \
--region us-east-1 \
--service-name execute-api \
--profile production
Example 5: With Server-Sent Events and Timeout
sigv4-proxy \
--target-url https://abc123.execute-api.us-east-1.amazonaws.com \
--region us-east-1 \
--service-name execute-api \
--sse \
--timeout 30s
Example 6: With Custom Headers
sigv4-proxy \
--target-url https://abc123.execute-api.us-east-1.amazonaws.com \
--region us-east-1 \
--service-name execute-api \
--headers "X-Custom-Header=value,X-API-Version=v2"
See docs/examples.md for more detailed configuration examples.
AWS Credentials
The proxy uses the standard AWS SDK credential chain to load credentials. Credentials are loaded in the following order:
-
Environment Variables
AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEYAWS_SESSION_TOKEN(optional, for temporary credentials)
-
Shared Credentials File (
~/.aws/credentials)- Default profile or named profile specified via
--profileorAWS_PROFILE
- Default profile or named profile specified via
-
IAM Role (when running on AWS infrastructure)
- EC2 instance profile
- ECS task role
- Lambda execution role
Setting Up Credentials
Option 1: Environment Variables
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=AQoDYXdzEJr... # Optional, for temporary credentials
Option 2: AWS Credentials File
Create or edit ~/.aws/credentials:
[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
[production]
aws_access_key_id = AKIAI44QH8DHBEXAMPLE
aws_secret_access_key = je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
Then use the profile:
sigv4-proxy --profile production ...
Option 3: IAM Role (Recommended for AWS Infrastructure)
When running on AWS infrastructure (EC2, ECS, Lambda), the proxy will automatically use the IAM role attached to the instance/task/function. No additional configuration is needed.
For more details, see docs/aws-credentials.md.
Usage with MCP Clients
Claude Desktop
Add the proxy to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"iam-protected-server": {
"command": "/path/to/sigv4-proxy",
"args": [
"--target-url", "https://abc123.execute-api.us-east-1.amazonaws.com",
"--region", "us-east-1",
"--service-name", "execute-api"
]
}
}
}
Other MCP Clients
The proxy communicates via stdio, so it can be used with any MCP client that supports stdio transport. Configure your client to launch the proxy as a subprocess and communicate via stdin/stdout.
Troubleshooting
Common Issues
"configuration error: target URL is required"
Cause: The target URL was not provided.
Solution: Set MCP_TARGET_URL environment variable or use --target-url flag.
"failed to load AWS credentials"
Cause: AWS credentials are not configured or not accessible.
Solution:
- Verify credentials are set via environment variables,
~/.aws/credentials, or IAM role - Check that the profile name is correct if using
--profile - Ensure credentials have not expired (for temporary credentials)
"target URL must use http or https scheme"
Cause: The target URL is malformed or uses an unsupported protocol.
Solution: Ensure the target URL starts with https:// (or http:// for local testing).
"signature version must be 'v4' or 'v4a'"
Cause: An invalid signature version was specified.
Solution: Use either v4 or v4a for the --sig-version flag or AWS_SIG_VERSION environment variable.
For more troubleshooting tips, see docs/troubleshooting.md.
Security Considerations
- Credential Protection: The proxy never logs or exposes AWS credentials. Access keys are masked in logs.
- HTTPS Required: Target server connections should use HTTPS to protect data in transit.
- Signature Security: AWS SDK handles signature generation securely according to AWS specifications.
- No Credential Forwarding: The proxy does not forward credentials to the client.
Performance
- Connection Pooling: HTTP connections to the target server are reused for efficiency.
- Minimal Latency: Signing adds approximately 1-2ms overhead per request.
- Streaming: Large responses are streamed without buffering the entire payload in memory.
License
MIT License - see LICENSE file for details.
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for development setup, testing guidelines, and how to submit pull requests.
Support
For issues, questions, or contributions, please visit the GitHub repository.
