Skip to main content

OAuth for hosted connectors

If your hosted MCP connector needs to call an OAuth-protected external service (for example, it reads data from an API that requires a user-specific access token), MintMCP can broker the entire OAuth flow on its behalf. Your MCP connector does not need to implement OAuth itself—it only needs to accept a pre-obtained access token.

This works for all hosted connector deployment types: Docker containers, zip packages, npx commands, and CLI deployments.

If your connector has built-in OAuth​

If your MCP connector already implements its own OAuth redirect flow, strip it out or bypass it before deploying. Built-in OAuth flows don't work on MintMCP because the connector container is not publicly accessible—redirect URIs won't resolve. Instead:

  1. Remove or disable the connector's own OAuth handler.
  2. Have the connector accept a pre-obtained access token via header or environment variable.
  3. Configure MintMCP to broker the OAuth exchange (see Setup sequence below).

How it works​

  1. Admin configures the OAuth settings in the MintMCP connector settings after deployment: authorization URL, token URL, client ID and secret, scopes, and how to map the token to a header or environment variable on the hosted connector.
  2. When a user calls a tool through the hosted connector and has not yet authorized, MintMCP directs them in-context to OAuth to the underlying provider.
  3. On completion, MintMCP manages the access token and refresh token, and delivers the access token on every subsequent tool call—without the user having to re-authenticate.
  4. The hosted connector receives the access token via a request header (HTTP transport) or environment variable (stdio transport) on each call. It never participates in the OAuth exchange itself.

What the connector needs to do​

Your MCP connector needs to accept one thing: a pre-obtained access token delivered by MintMCP.

TransportDelivery methodExample
HTTPRequest headerAuthorization: Bearer <token>
stdioEnvironment variableACCESS_TOKEN=<token>

The header name and environment variable name are both configurable by the admin in MintMCP—your connector just needs to read a token from some header or env var. That's it. No authorization endpoints, no redirect URIs, no refresh token logic.

Setup sequence​

OAuth does not need to be working at deploy time. Deploy first, configure OAuth after.

  1. Deploy the connector using any method (Docker, npx, CLI, or web UI). The connector will start successfully without OAuth configured.
  2. Open the connector settings in the MintMCP admin portal after deployment.
  3. Configure the OAuth settings:
    • Authorization URL
    • Token URL
    • Client ID and client secret
    • Scopes
    • Token-to-header or token-to-environment-variable mapping
  4. Users connect and authenticate through MintMCP's OAuth flow. MintMCP handles all subsequent token refresh automatically.