> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turen.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP OAuth

> Authorize hosted MCP integrations safely

Hosted MCP Extensions can use OAuth with dynamic client registration, PKCE, state validation, and a local callback listener.

## Connect

1. Open **Extend**.
2. Select a hosted integration marked **Needs Auth**.
3. For fieldless hosted entries, click **Connect** on the card.
4. Complete authorization in the system browser.
5. Return to TurenOS; the card updates to **Connected** after token exchange and tool discovery.

Entries with required configuration open a dialog before authorization.

```mermaid theme={null}
sequenceDiagram
  participant U as User
  participant T as TurenOS
  participant B as System browser
  participant P as MCP provider
  U->>T: Connect
  T->>T: Create PKCE verifier and callback listener
  T->>B: Open authorization URL
  B->>P: Authorize requested scopes
  P-->>T: Callback with code and state
  T->>P: Exchange code for tokens
  T->>T: Seal tokens and discover tools
  T-->>U: Connected
```

## Callback safety

TurenOS starts the callback listener before opening the browser, binds OAuth state to the MCP name, validates the callback state, and clears pending verifier/state data after completion, failure, timeout, or cancellation.

Refresh and access tokens are stored through the Secret Vault. They are not written into Extension manifests.

## Browser failures

If the browser cannot be opened, TurenOS marks the connection failed immediately and clears the pending OAuth attempt instead of waiting indefinitely. Retry after checking your default browser and desktop logs.

<Warning>
  Review the provider's requested scopes before authorizing. OAuth grants the remote service access represented by those scopes; TurenOS permissions control agent use of discovered tools afterward.
</Warning>