OAuth for Tools

Many MCP servers require OAuth. Pipelines implements the OAuth 2.1 Authorization Code flow with PKCE (S256), following the MCP authorization spec.

Three ways to connect

1. Provider gallery (easiest). On the MCP Servers page, click a pre-configured provider tile — Pipelines already knows the right auth flow and endpoints. See the provider list in MCP Server Integration → Provider gallery.
2. Automatic client registration. For any MCP server whose metadata advertises Dynamic Client Registration, Pipelines registers an OAuth client for your org automatically. You don't need to set up an app in the vendor's console — just click Connect via OAuth and approve the consent screen.
3. Bring your own OAuth app. When the server doesn't support automatic registration, you'll register an OAuth application in the vendor's developer console yourself and paste the Client ID into the Add Tool Endpoint modal.

Connect an OAuth-protected MCP server

1. Navigate to MCP Servers → Add Tool Endpoint (or pick a provider from the gallery).
2. Stay on the MCP Server tab.
3. Fill in Name and URL. The URL must be the MCP endpoint (for example, https://mcp.example.com/mcp).
4. Set Authentication to OAuth 2.0.
5. Client ID (optional) — leave blank if the server supports automatic registration. Fill it in when the vendor requires you to bring your own app.
6. Click Connect via OAuth. A popup opens with the provider's consent screen.
7. Approve the requested permissions. The popup closes and returns to Pipelines, and the endpoint is saved with a fresh access and refresh token.

Token lifecycle

• Access tokens are attached automatically to tool calls. If the token is near expiry when a call is about to run, Pipelines refreshes it first. This is reactive (on-demand) — there is no background refresh job.
• Refresh tokens are stored encrypted. If the refresh token is revoked or expires permanently, the next tool call or Test Connection will fail with an auth error. Re-run the OAuth flow from the endpoint detail page to reconnect.

Health and OAuth

OAuth connection state is not a separate status — it rolls up into the endpoint's three standard health states: Healthy, Unhealthy, or Unknown. After the OAuth callback finishes, the endpoint typically sits at Unknown until the next Test Connection or pipeline run, which flips it to Healthy or Unhealthy based on the result.

Edge cases to know

• Consent popup timeout. If you leave the consent popup idle for too long before approving, the authorization state expires and the flow fails. Close the popup and click Connect via OAuth again.
• redirect_uri mismatch during consent. Only appears when bringing your own OAuth app. In your vendor's developer console, whitelist the callback URL shown by Pipelines during the flow. Contact support if you need the exact value for your deployment.
• Audience / resource-indicator parameters are not sent today. Servers that strictly require an audience parameter in the authorize request cannot be connected via this flow — let us know if you hit this.

Debugging checklist

1. Popup errors immediately. Usually means OAuth discovery failed. Confirm the MCP server exposes /.well-known/oauth-protected-resource or /.well-known/oauth-authorization-server, and that you pasted the canonical URL (no trailing slash issues).
2. Consent screen shows redirect_uri mismatch. Fix the allowlisted URI in the vendor's OAuth app configuration.
3. "Client ID missing" on providers without automatic registration. Register an OAuth app in the provider's console, then edit the endpoint and paste the Client ID.
4. Intermittent Unhealthy. Sometimes a transient token-refresh failure. Click Test Connection again; if it recovers, the previous probe hit the refresh window.

Further reading

• OAuth 2.1 draft
• PKCE (RFC 7636)
• Dynamic Client Registration (RFC 7591)
• Protected Resource Metadata (RFC 9728)
• Authorization Server Metadata (RFC 8414)
• MCP authorization spec