MCP - AWS SigV4 Auth

Use AWS SigV4 authentication to connect LiteLLM to MCP servers hosted on AWS Bedrock AgentCore.

Why SigV4?

AWS services authenticate requests using Signature Version 4 — a per-request signing protocol that includes the request body in the cryptographic signature. This is fundamentally different from static-header auth types (api_key, bearer_token, etc.) which send the same header on every request.

LiteLLM's aws_sigv4 auth type handles this automatically: every outgoing MCP request is signed with your AWS credentials before it's sent.

Quick Start

1. Navigate to MCP Servers and click Add New MCP Server
2. Set the transport to Streamable HTTP
3. Select AWS SigV4 as the authentication type
4. Fill in your AWS credentials:

<br/>

Once created, LiteLLM will sign every outgoing MCP request with SigV4. The server's tools appear automatically in the MCP Tools list.

Editing credentials: When editing an existing SigV4 server, leave credential fields blank to keep the current values. Only fields you fill in will be updated.

1. Set AWS credentials

2. Add your AgentCore MCP server to config.yaml

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY

mcp_servers:
  my_agentcore_mcp:
    url: "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/<url-encoded-ARN>/invocations"
    transport: "http"
    auth_type: "aws_sigv4"
    aws_role_name: os.environ/AWS_ROLE_ARN          # IAM role to assume (recommended)
    aws_session_name: "litellm-prod"                 # optional — for CloudTrail auditing
    aws_region_name: "us-east-1"
    aws_service_name: "bedrock-agentcore"

:::info URL encoding

The AgentCore runtime ARN must be URL-encoded in the url field. For example:

arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my-mcp-server

becomes:

arn%3Aaws%3Abedrock-agentcore%3Aus-east-1%3A123456789012%3Aruntime%2Fmy-mcp-server

:::

3. Start the proxy

litellm --config config.yaml

Use the MCP tools

Once configured, your AgentCore MCP tools are available through LiteLLM like any other MCP server:

curl http://localhost:4000/mcp-rest/tools/list \\
  -H "Authorization: Bearer sk-1234"

curl http://localhost:4000/mcp-rest/tools/call \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer sk-1234" \\
  -d '{
    "name": "my_agentcore_mcp_your_tool_name",
    "arguments": {"key": "value"}
  }'

Config Reference

How It Works

LiteLLM uses an httpx.Auth subclass (MCPSigV4Auth) that hooks into the HTTP request lifecycle:

1. For every outgoing MCP request, the auth handler computes a SHA-256 hash of the request body
2. It creates a SigV4 signature using your AWS credentials, the request URL, headers, and body hash
3. The signed Authorization and x-amz-date headers are added to the request
4. AWS validates the signature and processes the MCP request

This happens transparently — no manual token management required.

Using Temporary Credentials (STS)

If you use AWS STS temporary credentials (e.g., from IAM roles or SSO), include the session token:

mcp_servers:
  my_agentcore_mcp:
    url: "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/<url-encoded-ARN>/invocations"
    transport: "http"
    auth_type: "aws_sigv4"
    aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
    aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
    aws_session_token: os.environ/AWS_SESSION_TOKEN
    aws_region_name: "us-east-1"
    aws_service_name: "bedrock-agentcore"

Using IAM Role Assumption (AssumeRole)

For production environments where your LiteLLM instance authenticates via an IAM role (e.g., EKS pod role, EC2 instance profile), you can configure aws_role_name to have LiteLLM call sts:AssumeRole before signing MCP requests:

mcp_servers:
  my_agentcore_mcp:
    url: "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/<url-encoded-ARN>/invocations"
    transport: "http"
    auth_type: "aws_sigv4"
    aws_role_name: "arn:aws:iam::123456789012:role/BedrockAgentCoreRole"
    aws_session_name: "litellm-prod"    # optional
    aws_region_name: "us-east-1"
    aws_service_name: "bedrock-agentcore"

LiteLLM uses the ambient credentials (pod role, instance profile, or env vars) to call sts:AssumeRole, then signs MCP requests with the assumed role's temporary credentials.

You can also combine aws_role_name with explicit access keys — the keys are then used as the source identity for the AssumeRole call:

mcp_servers:
  my_agentcore_mcp:
    url: "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/<url-encoded-ARN>/invocations"
    transport: "http"
    auth_type: "aws_sigv4"
    aws_role_name: os.environ/AWS_ROLE_ARN
    aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
    aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
    aws_region_name: "us-east-1"

:::tip For most Kubernetes deployments, you only need aws_role_name and aws_region_name — the pod's IAM role provides the source credentials automatically. :::

Troubleshooting

403 Forbidden from AWS

• Verify your AWS credentials are valid and not expired
• Check that aws_region_name matches the region in your AgentCore URL
• Ensure aws_service_name is set to bedrock-agentcore
• If using STS credentials, confirm aws_session_token is set and not expired

AssumeRole AccessDenied

If you get AccessDenied when using aws_role_name:

• Verify the role ARN is correct
• Check that the trust policy on the target role allows your source identity to assume it
• If running on EKS, ensure the pod's service account is annotated with the correct IAM role
• Check CloudTrail for the failed sts:AssumeRole call to see the exact error

Health check errors on startup

SigV4-authenticated MCP servers skip the standard health check on proxy startup. This is expected — the proxy will still sign requests correctly when tools are invoked.

"botocore not found" error

Install the botocore package:

uv add botocore

botocore is used for SigV4 credential handling and is required when using aws_sigv4 auth.