
The Euler Stream MCP server supports two mutually exclusive authentication modes for tool calls that require user identity.
These two modes are **XOR** — you must choose one or the other per connection.

## Authentication Modes

| Mode | URL Parameter | Auth Parameter | Login Flow Required |
|------|--------------|----------------|---------------------|
| **OAuth Mode** | `oauth=true` | `x-oauth-token` | Yes — OAuth login flow |
| **Cookie Mode** (default) | _(none)_ | `x-cookie-header` | No |

- **OAuth Mode** — The server requires an OAuth access token obtained through the [Euler OAuth flow](/docs/oauth). The server itself handles the login flow.
- **Cookie Mode** (default) — The caller supplies raw TikTok cookies directly via the `x-cookie-header` parameter. No OAuth login is required.

## URL Format

The authentication mode is determined by the `oauth` query parameter on the MCP endpoint URL.
This is set **at connection time**, not per tool call.

<TemplateCode code={`# OAuth mode
$baseUrl/mcp?oauth=true&apiKey=$apiKey

# Cookie mode (default)
$baseUrl/mcp?apiKey=$apiKey`} />

## OAuth Mode (oauth=true)

When `oauth=true` is set on the MCP endpoint URL:

- The MCP server **requires** the OAuth login flow to be completed before tools can execute.
- Tools accept `x-oauth-token` — the access token from an authorized [Euler OAuth app](/docs/oauth).
- The `x-cookie-header` parameter is **not accepted** and will be ignored.

## Cookie Mode (default)

When `oauth` is omitted or set to `false`:

- No OAuth login flow is required to connect.
- Tools accept `x-cookie-header` — raw TikTok cookies for direct authentication.
- The `x-oauth-token` parameter is **not accepted** and will be ignored.

## Using the Playground

Each tool's playground panel includes an **OAuth Mode** switch at the top. Toggling it:

- Updates the **URL preview** to show the endpoint with or without `?oauth=true`, reflecting the selected server host.
- Enables the corresponding authentication field (`x-oauth-token` or `x-cookie-header`) and **disables** the other with a lock icon.
- When running a tool, the playground connects to the MCP server using the correct URL for the selected mode.

The URL preview always reflects the **Server Host** selected in the sidebar picker, so switching servers updates the preview automatically.

## MCP Client Configuration

When configuring an external MCP client (Claude Desktop, Cursor, etc.), append `?oauth=true` to the MCP endpoint URL to enable OAuth mode.

<Tabs items={["OAuth Mode", "Cookie Mode (default)"]}>
<Tab>
<TemplateCode code={`{
  "mcpServers": {
    "euler-stream": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "$baseUrl/mcp?oauth=true&apiKey=$apiKey"
      ]
    }
  }
}`} />
</Tab>
<Tab>
<TemplateCode code={`{
  "mcpServers": {
    "euler-stream": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "$baseUrl/mcp?apiKey=$apiKey"
      ]
    }
  }
}`} />
</Tab>
</Tabs>

<Callout type="info">
When using OAuth mode, the MCP client will need to complete the OAuth authorization flow on first connection. The server will guide the client through the process.
</Callout>

## Pinning a User

When using OAuth mode, the authorization flow normally shows an account picker if the user has previously logged in. You can skip this step by passing `pinned_user_id` to the MCP endpoint URL, which automatically selects a specific TikTok user's cached session:

<TemplateCode code="$baseUrl/mcp?oauth=true&apiKey=$apiKey&pinned_user_id=6779789250017592326" />

The `pinned_user_id` parameter is optional. If the user has a valid cached session, authorization completes instantly with no user interaction. If not found, the normal flow continues silently.

This is useful for MCP clients that manage a specific user context and want to avoid the account picker on reconnection.

<Callout type="info">
For full details on how `login_user_id` works, including edge cases and fallback behavior, see the [OAuth Authorization Flow](/docs/oauth/authorization-flow#pinning-a-user-with-login_user_id) documentation.
</Callout>
