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, so 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 Hosted OAuth card in the MintMCP connector settings after deployment: the provider's endpoints, client credentials, scopes, and how token response fields map to headers or environment variables 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.

Transport	Delivery method	Example
HTTP	Request header	Authorization: Bearer <token>
stdio	Environment variable	ACCESS_TOKEN=<token>

The header name and environment variable name are both configurable by the admin in MintMCP, so 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.

Any field from the provider's token response can be mapped, not just access_token. If your connector also needs a value like instance_url, map it to an additional header or environment variable.

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 and find the Hosted OAuth card.
3. Configure the OAuth settings:
   • Authorization URL and Token URL from your OAuth provider
   • Client ID and Client Secret (the secret is optional; leave it blank for a public PKCE client)
   • Token Auth Method: client_secret_post or client_secret_basic, controlling how MintMCP authenticates to the provider's token endpoint
   • Scopes as a comma-separated list
   • Token response to header mappings (HTTP transport) or Token response to env mappings (stdio transport), for example mapping access_token to the Authorization header with prefix Bearer
4. Click Save OAuth.
5. Users connect and authenticate through MintMCP's OAuth flow. MintMCP handles all subsequent token refresh automatically.

Related

• Host STDIO servers with OAuth: Deploy a hosted connector and expose it to your team
• Hosted Server CLI: Deploy from the command line
• Docker images for hosted servers: Use a custom Docker image