FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started FAQ#

Which mode should I choose first?#

Use this default decision path:

streamable-http: best fit for modern MCP transport in production
sse: broad compatibility with existing MCP clients and integrations

If you are unsure, start with sse, complete validation, then migrate to streamable-http.

Why do I get `401 unauthorized`?#

Check the following in order:

MCP_AUTH_ENABLED=true is actually set in runtime environment.
MCP_AUTH_MODE is one of apikey, bearer, basic.
For apikey mode, MCP_AUTH_API_KEY is non-empty and matches request value.
API key is sent via X-Api-Key header or api_key query parameter.
Container/process was restarted after configuration changes.

Is API key header or query parameter preferred?#

Both are supported, but use request headers in production whenever possible:

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshooting#

Use this page as a practical playbook when setup or runtime behavior is not as expected.

1. Server fails to start#

Check port conflicts and startup logs:

1
2
3
4
5


# Check if port is occupied
ss -lntp | rg 8080

# Start with debug logs
./cloud-native-mcp-server --mode=sse --addr=127.0.0.1:8080 --log-level=debug

If using Docker, inspect container logs:

Getting Started on Cloud Native MCP Server

FAQ