---
title: "Start Mcp Oauth"
method: POST
path: "/v3/integrations/mcp/oauth/start"
tags: ["integrations-v3"]
---

# Start Mcp Oauth

`POST /v3/integrations/mcp/oauth/start`

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.

## Query parameters

- `organization_id` string, nullable

## Request body

- StartMcpOAuthRequest — Request body to begin an MCP OAuth authorization-code flow. Sent when the user clicks "Authorize" in the MCP integration form. The body carries only enough to perform OAuth discovery and Dynamic Client Registration — the integration's display name is supplied at the subsequent consume step.
  - `server_url` string, uri, required — Streamable HTTP / SSE endpoint URL of the MCP server.
  - `oauth_authorization_url` string, 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_url` string, uri, nullable — Optional manual override for the OAuth token endpoint. Must be HTTPS.
  - `oauth_scopes` string[] — Optional explicit list of OAuth scopes to request. When empty, the backend uses the server's advertised scopes.
  - `tool_call_timeout_ms` integer, nullable — Per-tool-call timeout carried onto the created integration.
  - `network_access` string, 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 `201`

Successful Response

- StartMcpOAuthResponse — Result of starting an OAuth flow.
  - `authorization_url` string, required — The OAuth authorization URL the popup should navigate to.
  - `pending_integration_id` string, required — Opaque ID of the pending OAuth flow. Pass this back when the popup finishes to consume the flow into a real integration.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/traversal/apis/fastapi.md) · [All operations](https://skmtc.net/traversal/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/traversal/fastapi/revisions/2134ebffd1ef/schema)