Configure a Gateway profile

A Gateway profile stores the OAuth and resource settings that MCP Stack uses when a server needs user-scoped auth. Create it from the Gateway page, inline during server generation, or through automation.

Setup workflow#

Every path ends with a working Connect flow and Gateway logs that show authorization and tool calls.

Requirements#

Before you start:

• a downstream OAuth authorization server (Auth0, Entra ID, SqlOS, or manual OAuth)
• an OAuth client ID registered for web/callback use
• the resource or audience your upstream API expects
• scopes that match the enabled MCP tools
• at least one MCP server that should use user-scoped auth

Dashboard path#

Gateway profiles live in their own workspace so OAuth settings can be reused across generated servers, agents, and external MCP clients.

1. Open Gateways.
2. Click Create Gateway.
3. Choose the provider type (Manual, Auth0, Entra ID, or SqlOS).
4. Enter the authorization server URL or metadata URL.
5. Enter the downstream OAuth client ID.
6. Enter the resource or audience.
7. Add scopes.
8. Save the profile.
9. Link one or more MCP servers from the Gateway detail page or server Gateway tab.
10. Register the callback URL in your OAuth provider.
11. Open the server Connect tab and run a test authorization.

You can also create a Gateway inline from the OpenAPI wizard Authentication step when generating a new server.

CLI path#

mcpstack gateways create \
  --name support-gateway \
  --provider manual \
  --authorization-server-url https://auth.example.com \
  --client-id your-client-id \
  --resource https://api.example.com \
  --scopes "openid profile email" \
  --json
 
mcpstack servers gateway attach support-api --gateway gw_support --json
mcpstack gateways get gw_support --json
mcpstack gateways logs gw_support

Inspect linked servers and recent auth events when debugging scope or audience mismatches.

API path#

Create a Gateway profile:

POST /api/v1/organizations/{orgId}/gateways
Authorization: Bearer {token}
Content-Type: application/json
 
{
  "name": "Support Gateway",
  "providerType": "manual",
  "authorizationServerUrl": "https://auth.example.com",
  "clientId": "your-client-id",
  "resource": "https://api.example.com",
  "scopes": ["openid", "profile", "email"]
}

Attach the profile to a server:

PUT /api/v1/organizations/{orgId}/mcp-servers/{serverId}/gateway
Authorization: Bearer {token}
Content-Type: application/json
 
{
  "gatewayId": "gw_support"
}

Read Gateway logs:

GET /api/v1/organizations/{orgId}/gateways/{gatewayId}/logs?page=1&pageSize=50

Callback URL#

Register the Gateway callback URL in the downstream OAuth provider. The Connect or Gateway page shows the exact value for the server/profile.

Typical provider checklist:

Application type: Web application
Allowed callback URL: copy from MCP Stack Gateway
Allowed logout URL: optional, provider-specific
Allowed origin: your MCP Stack origin if required
Scopes: least privilege for the enabled tools
Audience/resource: upstream API audience

Discovery fields#

Scope hygiene#

Start with openid, profile, email, and read scopes required by your first tools. Add write scopes only when the corresponding write tool is enabled and the downstream API enforces user-level authorization.

Embedded apps#

The same Gateway profile serves external MCP clients and embedded app-token exchange. See OAuth and Gateway fundamentals and Embed an agent with app auth.

Troubleshooting#

Quick answer#

Have the provider, issuer, client ID, resource/audience, scopes, and registered callback URL ready before you start. Most Gateway setup problems are a mismatch in one of those fields.