Initiate OAuth2 Flow
Three-step interactive PKCE flow for MCPs that authenticate via OAuth2 rather than a static API key:
POST /oauth2/initiate(this endpoint) - builds the provider's authorization URL and stores the PKCE verifier/state server-side. Redirect the end user's browser to the returnedauthorization_url.GET /oauth2/callback- the identity provider redirects here after the user authorizes (or denies) access; this exchanges the code for tokens and redirects back to the frontend URL supplied in step 1.GET /oauth2/sessions/{deployment_id}/{entry_id}- poll or read this afterward to checkconnectedstatus; never exposes the tokens themselves.DELETEthe same path to disconnect and force a fresh flow.
Calling initiate again for the same deployment/entry overwrites any
prior in-flight or completed session.
Start the PKCE authorization-code flow for an MCP's OAuth2 provider.
Keyed by listing (listing_id, or mcp_namespace resolved under the listing visibility rules), not a deployment: connecting a provider account does not require a deployment to exist first, since the resulting credential is reusable across every deployment the caller owns. deployment_id/entry_id are optional and, when both given, the entry's own listing is the one connected and the resulting credential is auto-linked to that entry once the callback completes - see oauth_callback.
Sets the browser-binding nonce cookie the callback checks; the caller must send this request with credentials so the browser keeps it.
Args: body: Listing to authorize, optional deployment/entry to auto-link, optional scope override, and the frontend URL to redirect back to once the flow completes. request: Used to build the callback redirect_uri from the current host, so it always matches how this API is being reached. response: Carries the nonce cookie. session: Database session. context: Caller's security context; the caller must own the deployment being auto-linked, if one is given.
Returns: The provider authorization URL the frontend should redirect the user to, plus the generated state value.
Authorization
OAuth2AuthorizationCodeBearer In: header
Query Parameters
trueRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Names the listing to connect by listing_id, or by mcp_namespace for callers that only know the namespace. A namespace is resolved with the listing visibility rules, preferring the public published listing; an entry (deployment_id + entry_id) overrides both with its own listing.
Response Body
application/json
application/json
curl -X POST "https://example.com/v1/oauth2/initiate" \ -H "Content-Type: application/json" \ -d '{ "redirect_uri": "string" }'{ "authorization_url": "string", "state": "string"}{ "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ]}