latestOpenAPI 3.1.02026-08-223321,1001.6 MB

2134ebffd1ef

integrations-v3

Start Mcp Oauth

Begin an MCP OAuth flow: discover, register, return the authorize URL.

The frontend POSTs to this endpoint, opens the returned authorization_url in a popup, and waits for either a postMessage from the popup or a positive status from mcp_oauth_pending_status. Once authorized, the integration is created via POST /v3/integrations/mcp/oauth/consume (create mode) or POST /v3/integrations/mcp/{id}/oauth/consume (re-auth mode).

Permissions: integration setup user.

post/v3/integrations/mcp/oauth/start

Query parameters

organization_idstring nullable

Request body

server_urlstring uri required

Streamable HTTP / SSE endpoint URL of the MCP server.

oauth_authorization_urlstring uri nullable

Optional manual override for the OAuth authorization endpoint. Must be HTTPS. When supplied alongside oauth_token_url the backend skips well-known discovery for those endpoints.

oauth_token_urlstring uri nullable

Optional manual override for the OAuth token endpoint. Must be HTTPS.

oauth_scopesstring[]

Optional explicit list of OAuth scopes to request. When empty, the backend uses the server's advertised scopes.

tool_call_timeout_msinteger nullable

Per-tool-call timeout carried onto the created integration.

network_accessstring nullable

Optional OrgConnector name to route the OAuth flow (discovery, DCR, token exchange) through. When set, the resolved connector URL is also persisted as the integration's relay_controller_proxy_url so runtime tool calls follow the same path.

Response

Successful Response

authorization_urlstring required

The OAuth authorization URL the popup should navigate to.

pending_integration_idstring required

Opaque ID of the pending OAuth flow. Pass this back when the popup finishes to consume the flow into a real integration.