Gateways

The Gateways page is where you set up the Descope Agent Gateway. You create a gateway, deploy it in your own infrastructure with the credentials Descope issues, and then add a route for every MCP server or API you want agents to reach through it.

For why you'd put a gateway in front of MCP at all, and how it compares to using Descope as the IdP for a gateway you already run, see MCP Gateways. This page covers the Console side.

How Gateways Work

A gateway is one public base URL that agents connect to. Each route on that gateway becomes its own Descope-protected endpoint, a separate Resource with its own audience, and forwards to one upstream MCP server.

When an agent calls a route, it presents a Descope token minted for that route's endpoint. The gateway then gets the credential the upstream needs. If the upstream is protected by Descope, the gateway exchanges the token for one with the upstream's audience. If it isn't, the gateway pulls a token or API key from the Connection you attached to the route. The agent never holds the upstream credential.

That split is the reason every upstream needs a route, including ones Descope doesn't protect. A third-party MCP server like HubSpot, or an internal API that uses some other authorization server, still gets a route. The route is what agents authenticate to and what policies evaluate.

Two Ways to Lay Out Routes

There are two common shapes, and you can mix them on the same gateway. In both, the entrance the agent connects to is its own audience, so the agent's token is only good at the gateway and never at a downstream service.

One route as a virtual MCP server. The agent connects to a single endpoint that exposes tools from several downstream services at once. That endpoint has its own audience. When a tool runs, the gateway gets the right credential for that tool in the middle of the call, either through Descope token exchange and Connection fetching, or through another STS you already use.

This is the simplest thing for agents: one server to configure, one consent. Access to individual tools comes down to the scopes on the route's token and what your policies allow at exchange time.

One route per downstream resource: Each distinct MCP server or API gets its own route, and each route has its own audience. The gateway exchanges the route token for that one upstream: a Resource token if the upstream is protected by Descope, or the credential from the route's Connection if it isn't.

Separate routes give you separate consent, scopes, and policies per downstream, and a cleaner audit trail, because every call names exactly which upstream it was for. The tradeoff is that agents connect to more than one endpoint. This is the layout the route screens below walk through.

Creating a Gateway

You can create as many gateways as you need, for example one per environment or one per product line. The Gateways page lists each one with its template, connection status, number of routes, and creation date.

To create one, click + New gateway and fill in:

• Name: A display name for the gateway.
• Base URL: The public URL where you'll deploy the gateway, such as https://mcp-gateway.example.com/mcp. Route endpoints are built under this URL.
• Description: Optional notes for your team.

Gateway Details

After you create a gateway, Descope automatically issues it a Client ID and Client secret. The deployed gateway uses these to authenticate to Descope when it performs token exchange and fetches Connection tokens on a route's behalf. Keep the secret on the gateway, never in an MCP client, and use Rotate secret if it may have been exposed.

Download agentgateway configuration downloads a configuration file for deploying the gateway with agentgateway. The gateway shows Awaiting connection until your deployment connects to Descope.

The Routes section lists every route on the gateway, with its endpoint URL and the Connection attached to it, including the scopes that Connection can mint.

Before You Add Routes

If a route fronts a third-party MCP server or API (HubSpot, Amplitude, an internal system that takes an API key), create a Connection for it first. The Connection is where Descope stores and refreshes the OAuth tokens or API keys that upstream needs, and you'll pick it when you add the route.

• For OAuth providers, register an app with the provider and create an OAuth Connection with its client ID and secret.
• For API keys, create an API Key Connection.
• Then get tokens into it for your users or tenants, using one of the methods in Storing Connection Tokens.

You can create Connections per tenant, so each of your customers gets their own client ID and secret, or their own API key. Set the Associated Tenant on the Connection (see Connection Details), or create tenant-specific instances from a DCR preset Connection. When a call comes in, Descope uses the Connection that matches the tenant on the agent's token. Multi-Tenancy with Connections covers how user and tenant tokens are kept apart.

You can skip this if upstream credentials come from somewhere else. If you use another STS, such as Azure issuing tokens for native Azure APIs, that STS handles the downstream tokens and you don't need a Descope Connection for those services. The same goes for your own MCP servers that already validate Descope tokens, covered below.

Adding Routes

Click + Add route to protect a new upstream. Adding a route takes two steps: pick the target, then decide how the gateway gets credentials for it.

Step 1: Choose the Target

You can pick one of the MCP servers already registered in your Descope project, or enter a Custom MCP server URL for anything else, such as https://mcp.hubspot.com.

Step 2: Attach Credentials

What you configure here depends on the kind of target.

Custom URLs

For a custom URL, give the route a Route Name, then choose where the upstream credential comes from.

If the upstream already validates Descope tokens itself, check Target authenticates callers with Descope. No Connection is attached in that case.

Otherwise, pick an Outbound connection. This is the Connection you set up earlier that supplies the upstream credential, an OAuth token for HubSpot or an API key for an internal system. The Connection's scopes act as a ceiling on what the gateway can mint toward the target. That ceiling is separate from who may reach the route in the first place, which your policies decide.

MCP Servers Registered in Descope

When the target is your own MCP server that is already registered in Descope, you choose an Endpoint type instead:

• Dedicated endpoint: The route gets its own audience, and the gateway token-exchanges to the upstream. This gives you a real trust boundary between the gateway and the server, and is usually what you want.
• Transparent proxy: The route reuses the upstream server's audience. Nothing new is created, and the upstream's own policies still govern access.

No external Connection is attached for these targets. If the MCP server needs third-party credentials of its own, it fetches them from Connections inside its tool handlers as usual.

Route Endpoints

Every route gets an endpoint under the gateway's base URL, such as https://mcp-gateway.example.com/mcp/mcp-hubspot-com. The path defaults to a slug of the target and you can edit it, but it has to be unique on the gateway. This is the URL agents connect to.

Next Steps

Write policies that decide which agents and users may reach each route, and with which scopes. If routes use Connections, make sure the tokens are stored for the right users or tenants, as covered in Storing Connection Tokens.

For the architecture behind routes and token exchange, see MCP Gateways. For B2B isolation and auditing patterns, see MCP Gateway Use Cases.