Guides and Tutorials/Model Context Protocol (MCP)

MCP Gateways

When you build an MCP gateway (a single entrypoint that fronts many MCP servers and/or tenants), Descope gives you a few core building blocks:

  • MCP server concepts define what each logical MCP server looks like (well-known, flows, sessions, DCR/CIMD, audiences, scopes, branding).
  • Connections per tenant define how each tenant MCP server is wired to downstream systems (credentials, endpoints, scope mapping).
  • Policies define who can call which MCP server, for which tenants, and with what capabilities (scopes).

With these three building blocks, you can design a flexible, multi-tenant MCP gateway on top of Descope that:

  • Scales to many tenants and MCP servers.
  • Keeps credentials and configuration isolated per tenant.
  • Enforces clear, auditable policies per server and agent set.

Where Descope Fits in the MCP Gateway

When an agent invokes a tool, the request typically will go through the gateway.

If the agent is not allowed to access that MCP server or scope, the gateway does not issue the connection or resource token and the agent has no access to that tool. If the policy allows, the gateway resolves the tenant-specific MCP server and its Connections.

The two scenarios below show how this works for different gateway architectures.

Scenario 1: Internal MCP Servers + Third-Party MCP Servers

In this scenario you are building an MCP gateway that connects two types of MCP servers:

  • MCP servers you build internally (e.g. your own MCP server).
  • Third-party MCP servers you do not build (e.g. Notion MCP, Linear MCP, or other remote community MCP servers).

Descope Connections manage the tokens for the third-party MCP servers. You can connect as many third-party MCP servers as you need using Connections, and scope them at the tenant level so each customer has their own credentials and scope mapping.

MCP Server A (internal) in the diagram below represents an MCP server that you build yourself. It shows the different ways you can use Descope within that server:

  • Resource tokens (e.g. for a Descope-protected API)
  • Connection tokens (e.g. for Google Calendar or other OAuth-backed APIs) and API key-based resources

The gateway enforces policy when the agent requests a connection or resource token; if the agent is not permitted for that MCP server or scope, the request is denied and the agent has no access to that tool.

The diagram below illustrates this mix of internal and third-party MCP servers:

Scenario 2: One MCP Server Per Customer

In this scenario you spin up a different MCP server for every customer. Each of these MCP servers is modeled as a separate MCP Server (resource) in Descope, with its own well-known, flows, scopes, and policies.

The gateway still enforces policy when the agent requests a connection or resource token; only permitted agents get access to a given customer’s MCP server.

Within each MCP server you build for a customer, you use token exchange to either:

  • Manage Connections (e.g. OAuth or API key-based tools), or
  • Issue API access tokens (e.g. Descope resource tokens for your own APIs).

The diagram below shows two such internal MCP servers (Server A and Server B), each connecting to its own set of backends:

  • Server A → API A (Descope OAuth Resource) and API B (API key)
  • Server B → API C (Descope OAuth Resource) and API D (API key)

No third-party MCP servers are involved; each server is your own, per-customer deployment.

In both scenarios, policies are evaluated when the gateway issues a connection or resource token.

If the agent is not permitted for that MCP server or scope, the request is denied and the agent cannot use that tool.

MCP Servers per Tenant

In a gateway, you often have multiple logical MCP servers behind a single public endpoint. For example:

  • One MCP server per customer or tenant.
  • One MCP server per product domain (e.g. “billing MCP”, “analytics MCP”).

In Descope, you model each of these as its own MCP Server, with:

  • Well-known MCP server metadata - each server can expose its own .well-known configuration (endpoints, capabilities, etc.).
  • Client registration templates - define the default client registration behavior and UX:
    • Flows - which Descope Flow runs when a client registers (e.g. consent, MFA, attribute collection).
    • Session management - how long sessions last, idle timeouts, refresh behavior.
    • Branding - logo, colors, and consent screen text specific to that MCP server or tenant.
  • DCR / CIMD settings - dynamic client registration or client-initiated metadata discovery configuration per server.
  • Audience and scopes (resource definitions) - what each MCP server exposes:
    • Audience - the resource identifier your agents target (e.g. https://mcp.example.com/tenant-a).
    • Scopes - fine-grained permissions (e.g. mcp:read, mcp:write:invoices, mcp:run:tools).

You can create one MCP server per tenant, even if they are all backed by the same runtime code. This lets you:

  • Give each customer their own session configuration (e.g. stricter or more relaxed timeouts).
  • Run different Flows for different customers (e.g. extra consent, extra attributes, custom legal text).
  • Customize branding per customer (logos, product name, colors).

Connections per Tenant

Descope Connections are not just global integrations - you can also scope them to a specific tenant.

This is powerful for MCP gateways because:

  • Each tenant may need its own credentials for downstream systems:
    • OAuth client IDs/secrets.
    • API keys.
  • Each tenant may need different Connection scope mappings.

For an MCP gateway, you can:

  • Create Connections per tenant that hold:
    • Tenant-specific OAuth credentials for the tenant's MCP server.
    • Tenant-specific API keys or secrets for the tools that MCP server exposes.
    • Any custom headers, base URLs, or configuration needed to talk to that tenant's environment.

Connections per tenant

  • Use those Connections in your Flows so that:
    • When a request targets a given tenant's MCP server, Descope automatically uses that tenant's Connection.
    • Scope/permission mapping happens per tenant (for example, mcp:read at the gateway can map to different underlying scopes per tenant MCP server).

Mapping per MCP server

This lets you run a single gateway codebase while isolating credentials, endpoints, and scope mappings per tenant.

Policies Per MCP Server (Tenant-Specific)

Descope Policies let you define who can talk to what, and under which rules:

  • Which agents/clients are allowed to access a given MCP server.
  • Which scopes they can request and under what conditions.
  • Any additional constraints (e.g. IP allowlists, tenant constraints, environment).

In an MCP gateway, you can:

  • Create multiple policies, each tied to:
    • A specific MCP server (for example, “Tenant A MCP server”).
    • A specific set of agents or client types (for example, “internal tools”, “customer LLM gateway”, “partner agents”).
  • Express different rules per combination, such as:
    • “Agents in group X can only access mcp:read on Tenant A's MCP server.”
    • “Agents in group Y can run write tools (mcp:write:*) only on a staging MCP server, not production.”
    • “External partner agents can access only specific MCP servers with a limited scope set.”

Policies per MCP server

Was this helpful?

Calendar MCP Server (w/ SSO)

Learn how to build a secure calendar MCP server with SSO authentication, permission-based scopes, and multi-tenant support.

Golf.dev

Use Descope as the identity and authorization layer for MCP servers, with Golf.dev Gateway enforcing access policies at runtime.

On this page