Documentation

Troubleshooting

TLS interception, credentials, and endpoint issues — and how to resolve them.

TLS: certificate signed by unknown authority

On a corporate network, a TLS-intercepting proxy — such as Zscaler or Cloudflare WARP — terminates HTTPS and re-signs it with an internal certificate authority. If that CA isn’t in the trust store, connecting to the endpoint fails with:

x509: certificate signed by unknown authority

The proxy trusts the operating system’s root store by default. To trust your organization’s CA without modifying the system store, point --ca-bundle (or the AWS_CA_BUNDLE environment variable) at a PEM file containing the corporate root:

export AWS_CA_BUNDLE=/etc/ssl/corp-root.pem
aws-mcp-proxy https://<endpoint>.api.aws/mcp

The bundle is trusted in addition to the system roots, so first-party AWS endpoints keep working.

Credentials: unable to sign the request

Signed endpoints need AWS credentials from the standard chain — environment variables, shared config, a named profile, or SSO. If none are found, the request can’t be signed.

Run doctor first to see the SDK credential source and the effective STS identity:

Assume-role and chained-role profiles use the AWS shared-config chain without special proxy flags. Confirm the final profile independently, then use that same profile with the proxy:

aws sts get-caller-identity --profile <final-role-profile>
aws-mcp-proxy https://<endpoint>.api.aws/mcp --profile <final-role-profile>

If the final role uses a source_profile backed by credential_process, the proxy resolves the process credentials before calling STS. Credential processes cannot read the proxy’s MCP stdio stream.

For an unsigned endpoint, such as the public AWS documentation MCP server, skip signing entirely:

--skip-auth is strict: it does not load AWS credentials and sends every upstream request unsigned. For an endpoint that accepts either signed or unsigned traffic, use --optional-auth instead.

Region or service not detected

The SigV4 service and region are inferred from the endpoint host, including *.api.aws and bedrock-agentcore endpoints. For a host that doesn’t follow those patterns, set them explicitly:

Turn on debug logging

When the cause isn’t obvious, raise the log level to surface credential resolution, TLS setup, and upstream request detail on stderr:

Doctor suppresses recovered transport negotiation by default. Pass --log-level DEBUG explicitly when you need its underlying STS or MCP transport logs.