Choose runtime auth mode

Runtime auth is how the generated MCP runtime reaches the upstream API. MCP Stack exposes three modes in the dashboard wizard: Public API, Static Headers, and Gateway.

Use Gateway when the access boundary is user-scoped. Use Static Headers only for fixed upstream credentials.

Public API#

Choose Public API when the runtime does not need to inject credentials.

Good fits:

• Public demo APIs.
• Public data APIs.
• APIs protected outside the runtime by a trusted private network.

Hosted runtime behavior:

# No upstream auth variables are injected.
mcpstack servers create --openapi-url https://api.example.com/openapi.json

Static Headers#

Choose Static Headers when every upstream request should include the same fixed header.

Good fits:

• Server-to-server API keys.
• A tenant header for a demo or internal environment.
• A fixed upstream bearer token that does not represent the signed-in user.

Example generated runtime configuration:

UPSTREAM_BASE_URL=https://api.example.com
UPSTREAM_HEADERS='{"X-API-Key":"${SUPPORT_API_KEY}","X-Tenant-Id":"demo"}'

Do not use Static Headers for user OAuth. A shared Authorization value means every user would call the upstream API as the same identity.

MCP Stack Gateway#

Choose Gateway when the upstream API is protected by OAuth, OpenID Connect, or bearer tokens that should represent the real user.

Gateway needs:

• Authorization server issuer or metadata URL.
• OAuth client ID.
• Resource or audience.
• Scopes.
• Callback URL registered with the downstream provider.

Example CLI setup:

mcpstack servers create \
  --name support-api \
  --openapi-url https://api.example.com/openapi.json
 
mcpstack gateways create \
  --name support-api-gateway \
  --provider auth0 \
  --auth-server-url https://auth.example.com \
  --client-id support-api-mcp \
  --resource https://api.example.com \
  --scopes "openid profile email tickets.read tickets.write"
 
mcpstack servers gateway attach <server-id> --gateway <gateway-id>

Auto-detection#

The dashboard wizard reads OpenAPI security schemes and recommends a mode:

Auto-detection is a recommendation, not a substitute for product judgment. If the upstream access token changes by user, choose Gateway.

Runtime auth checklist#

Before creating the server:

• Confirm whether upstream calls should run as the user or as the application.
• Confirm the scopes required for read tools and write tools.
• Remove write scopes until the corresponding tools are actually enabled.
• Confirm whether the runtime should be hosted by MCP Stack Host.
• Confirm whether external clients need OAuth discovery metadata.

Quick answer#

Use this decision rule:

Public API means no upstream credentials. Static Headers means one fixed upstream credential. Gateway means user-scoped OAuth, OIDC, bearer access, public MCP discovery, and downstream grant storage.