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), Mintive 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 Mintive 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 Mintive to broker the OAuth exchange (see Setup sequence below).

How it works​

  1. Admin configures the Hosted OAuth card in the Mintive 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, Mintive directs them in-context to OAuth to the underlying provider.
  3. On completion, Mintive 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 Mintive.

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

The header name and environment variable name are both configurable by the admin in Mintive, 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 Mintive 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 Mintive 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 Mintive's OAuth flow. Mintive handles all subsequent token refresh automatically.

Share one OAuth connection with everyone​

By default each user connects their own account, so every tool call runs with that user's permissions on the provider. Switch the connector to shared credentials when the whole team should use one account instead, for example a service account or a provider that only allows one connection per workspace.

  1. Open the connector settings and find the Hosted OAuth card. The OAuth settings must already be saved.
  2. Under Credential Management, below the card, select Shared credentials. You need manager access to the connector.
  3. Connect your account if you haven't already. Your connection becomes the one everyone uses.

Once sharing is on, only the manager who enabled it can connect or disconnect the account. Other users see Authorized via shared Hosted OAuth credential on the connector and don't connect anything themselves. To hand the connection to a different manager, have them select Per-user credentials and then Shared credentials again, then connect their own account.

  • Every tool call runs with the shared account's permissions on the provider, and the provider's own audit log attributes those calls to that account. Mintive still logs which user made each call, so use Virtual MCP access policies to control who can reach the connector.
  • Connecting, reconnecting, or disconnecting the shared account is written to the audit trail, the same as any other stored credential.
  • If the shared account is disconnected, or the provider stops accepting its refresh token, the connector stops working for everyone until the owning manager reconnects.
  • Agent identities keep their own connection on the connector, so agents don't use the shared account.