Connections
Descope Connections provide secure, tenant and user-scoped integration with third-party services. The most common use of Connections is within an MCP Server, where they act as a token vault for storing and refreshing the external service tokens or API keys required to execute MCP tools.
Connections support both OAuth providers (for interactive login and consent) and API-key based services (for machine or user-supplied secrets). Your MCP server retrieves these credentials at runtime using Descope SDKs or APIs, ensuring external tokens are managed centrally and never hardcoded in your infrastructure.
If you're building AI agents or MCP servers that need access to external services (e.g., Google Calendar, Salesforce), Connections handle secure storage, token refresh, and access control. Your tools can reliably retrieve user/tenant-scoped OAuth tokens or API keys whenever they need to call third-party APIs.
How It Works
- Create a Connection
- Choose a preconfigured OAuth provider, or create a custom connection for any service (including API key storage).
- Connect Users or Tenants
- Use Descope SDKs or APIs to connect users to OAuth providers or to collect and store API keys.
- Token Vault
- Descope securely stores and manages all tokens and API keys, making them available for backend or agent use.
Creating a Connection
To set up a connection in Descope, follow the steps in our Creating a Connection guide.
Storing Connection Tokens
How you connect and store tokens with Connections depends on the Connection type you've created:
OAuth Provider Connections
OAuth connections are interactive and require an end user to authenticate via a browser-based redirect. Currently, only the OAuth authorization code flow is supported, meaning users must sign in through the provider's consent screen in a browser.
After successful login and consent, Descope stores the access and refresh tokens on behalf of that user and makes them available to the MCP server at runtime.
You can optionally include connection requests directly inside your User Consent Flow so that, when a user signs in to your MCP server, they are also guided through third-party OAuth consent using Outbound App connect actions (such as OAuth or API-key connect screens). This allows you to combine MCP login and third-party service consent into a single, seamless authentication experience.
MCP servers can also return an /authorize URL to clients using our Adaptive Connect feature, which allows the client to automatically launch the OAuth login and consent screen. When this URL is a Descope-hosted authorization URL, users authenticate with the OAuth provider, consent to requested scopes, and return a token back to Descope. That token is then available for MCP tool execution.
API Key Connections
API-key based connections store static secrets for external services. These API keys can be added in two ways. You may upload them directly using the Outbound App CRUD APIs, or you may collect them interactively in a Descope Flow using the Outbound App API Key Connect action, which renders a secure input screen for users to submit an API key. Once submitted, the API key is vaulted inside the Connection and becomes available to your MCP server for tool execution.
For machine-to-machine agents or backend automation, API keys can also be inserted programmatically via SDK or API without user interaction, depending on your integration design.
Token Management
Once you have tokens stored with Descope, associated with your Connection, you can view them from within the token management tab. These are all of the things you can view for each token:
- ID: System-generated ID pairing that user's consent to the application.
- App ID: The configured application ID which coincides with the token ID.
- Associated User: The user ID of the user who's associated with the consent.
- Scopes: The consented scopes correlate to the user's consent to the application.
- Access Token Expiration: Expiration of the current access token for the user's consent.
- Refresh Token: Boolean indicating whether a refresh token is available.
- Last Refreshed: The last time the user's access token was refreshed.
- Last Refresh Error: If applicable, the last error encountered while trying to refresh the user's access token.
- Token Subject: The user reference on the provider side. For this example, it is associated with the unique user ID of the user's Google account.
- Access Token Type: Specifies the format or method the access token uses, such as Bearer or MAC, which determines how it is used for authentication and authorization.
- Tenant ID: The tenant ID of the tenant associated with the consent.
You can also view the tokens in plain text, manually refresh any of the tokens (if OAuth-based), or delete any tokens from this tab.
You can also remove tokens using our SDKs, documented here.
Fetching Your Connection Tokens
Once your users/tenants are connected and have tokens stored in our Connections vault, you can start fetching the tokens to access third-party APIs within your MCP server or with your agents.