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

# MCP Server

> Connect any MCP-compatible AI assistant to Upriver — real-time intelligence on what's breaking out online and the creators behind it.

Upriver's hosted **Model Context Protocol (MCP)** server brings real-time, evidence-backed context to any MCP-compatible assistant or agent. It's remote and hosted — there's nothing to install or run.

Upriver tracks online culture in real time — both **what's** gaining traction and **who's** driving it. The server exposes two complementary slices:

* **Breakout topics** — *what's* emerging: subjects gaining traction across tech, sports, and politics, each with grounded source citations so the model reasons from real evidence instead of guessing.
* **Creators** — *who's* behind it: find creators by name, content, or audience filters, then pull a full profile to vet them.

The two chain naturally — spot what's breaking out, then find the creators driving it (or start from a creator and see what's resonating).

<Note>
  Upriver MCP access is provisioned per account. Connect any client below to sign in — if your account isn't enabled yet, you'll be pointed to [request access](https://dashboard.upriver.ai).
</Note>

## Connect

|               |                                                                              |
| ------------- | ---------------------------------------------------------------------------- |
| **Endpoint**  | `https://mcp.upriver.ai/mcp`                                                 |
| **Transport** | Streamable HTTP                                                              |
| **Auth**      | Sign in with Upriver (OAuth), or send your API key in the `X-API-Key` header |

<Info>
  **OAuth sign-in works in every client.** The `X-API-Key` header is supported by Claude Code, Cursor, VS Code, Cline, Windsurf, Codex CLI, Goose, and Zed — but **not** by Claude's or ChatGPT's connector UIs, which are OAuth-only.
</Info>

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http upriver https://mcp.upriver.ai/mcp
    ```

    To use an API key instead of OAuth, pass it as a header:

    ```bash theme={null}
    claude mcp add --transport http upriver https://mcp.upriver.ai/mcp \
      --header "X-API-Key: YOUR_UPRIVER_API_KEY"
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project), then connect it in **Settings → Tools & Integrations** to sign in:

    ```json theme={null}
    { "mcpServers": { "upriver": { "url": "https://mcp.upriver.ai/mcp" } } }
    ```

    For API-key auth, add `"headers": { "X-API-Key": "YOUR_UPRIVER_API_KEY" }`.
  </Tab>

  <Tab title="VS Code">
    VS Code uses a different shape — top-level **`servers`** and a required **`"type": "http"`**. Add to `.vscode/mcp.json` (or run **MCP: Add Server**):

    ```json theme={null}
    { "servers": { "upriver": { "type": "http", "url": "https://mcp.upriver.ai/mcp" } } }
    ```

    For API-key auth, add `"headers": { "X-API-Key": "YOUR_UPRIVER_API_KEY" }`.
  </Tab>

  <Tab title="Claude (Desktop & web)">
    In Claude, go to **Customize → Connectors → "+" → Add custom connector**, name it `Upriver`, paste `https://mcp.upriver.ai/mcp`, then **Connect** and sign in.

    <Note>Claude's connector is OAuth-only — there's no field for an API key. Don't add a raw `url` entry to `claude_desktop_config.json`; the desktop app rejects it.</Note>
  </Tab>

  <Tab title="Cline">
    Use the **Remote Servers** tab (Transport: **Streamable HTTP**), or edit `cline_mcp_settings.json`. The `type` field is required, or Cline falls back to legacy SSE and fails:

    ```json theme={null}
    { "mcpServers": { "upriver": { "type": "streamableHttp", "url": "https://mcp.upriver.ai/mcp" } } }
    ```
  </Tab>

  <Tab title="Windsurf">
    Edit `~/.codeium/windsurf/mcp_config.json` — Windsurf's field is **`serverUrl`**:

    ```json theme={null}
    { "mcpServers": { "upriver": { "serverUrl": "https://mcp.upriver.ai/mcp" } } }
    ```
  </Tab>
</Tabs>

<AccordionGroup>
  <Accordion title="More clients — Codex CLI, ChatGPT, Goose, Zed">
    **Codex CLI (OpenAI)**

    ```bash theme={null}
    codex mcp add upriver --url https://mcp.upriver.ai/mcp --header X-API-Key=YOUR_UPRIVER_API_KEY
    ```

    **ChatGPT** — Enable **Developer mode** (Settings → Apps & Connectors → Advanced), then **Settings → Connectors → Create**, name it `Upriver`, paste `https://mcp.upriver.ai/mcp`, choose **OAuth**, and sign in. (No custom-header field — OAuth only in the UI.)

    **Goose** — add to `~/.config/goose/config.yaml`:

    ```yaml theme={null}
    extensions:
      upriver:
        type: streamable_http
        uri: https://mcp.upriver.ai/mcp
        enabled: true
        headers:
          X-API-Key: "${UPRIVER_API_KEY}"
    ```

    **Zed** — add to `settings.json` under `context_servers`:

    ```json theme={null}
    { "context_servers": { "upriver": { "url": "https://mcp.upriver.ai/mcp", "headers": { "X-API-Key": "YOUR_UPRIVER_API_KEY" } } } }
    ```
  </Accordion>
</AccordionGroup>

<Note>
  **JetBrains IDEs:** MCP works, but the IDE currently drops custom request headers and doesn't yet support OAuth for remote servers, so Upriver's `X-API-Key` auth can't connect there yet — we'll list it once JetBrains ships the fix.
</Note>

## Tools available today

Four read-only tools across the two slices. **Breakout topics** answer *what's* gaining traction; **creators** answer *who's* driving and relevant to it — so you can go from a trend to the people behind it, or start from a creator and see what's resonating.

### Breakout topics

Subjects gaining traction across tech, sports, and politics. Each tool returns up to 25 topics per call (default 10), every topic carrying up to 5 source citations, with a `has_more` flag when more results exist beyond the page.

**`breakout_search_topics`** — search breakout topics by keyword.

| Parameter          | Type                  | Description                                               |
| ------------------ | --------------------- | --------------------------------------------------------- |
| `query`            | string · **required** | Natural-language search, e.g. `"AI video effects"`.       |
| `vertical`         | enum                  | Restrict to `tech`, `sports`, or `politics`.              |
| `limit`            | integer               | 1–25 (default 10).                                        |
| `citation_sources` | array                 | Restrict citations to any of `news`, `reddit`, `twitter`. |

**`breakout_list_topics`** — browse breakout topics gaining traction right now.

| Parameter          | Type    | Description                                                                                      |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------ |
| `vertical`         | enum    | Restrict to `tech`, `sports`, or `politics`.                                                     |
| `status`           | enum    | Lifecycle filter: `active` (default), `emerging`, `trending`, `declining`, `detected`, or `all`. |
| `limit`            | integer | 1–25 (default 10).                                                                               |
| `citation_sources` | array   | Restrict citations to any of `news`, `reddit`, `twitter`.                                        |

Each topic includes its name, vertical, lifecycle status, a momentum signal, and its top citations (title, URL, source category, and publish time).

### Creators

Find and vet creators across platforms — start with `creator_search` to find matches, then `creator_get` to pull one creator's full profile.

**`creator_search`** — find creators by name/@handle, by what their content is about, or by filters. Returns lean matches (top channels + categories) plus `next_cursor` for paging. At least one of `name_or_handle`, `content_query`, or a filter is required.

| Parameter                              | Type    | Description                                                                                                                                     |
| -------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `name_or_handle`                       | string  | Find a creator by display name or @handle (exact, prefix, fuzzy).                                                                               |
| `content_query`                        | string  | Describe the creator or content in plain language; results ranked by content match.                                                             |
| `categories`                           | array   | Free-text category keywords, e.g. `["gaming"]` or `["beauty", "skincare"]`.                                                                     |
| `platforms`                            | array   | Restrict to platforms — `youtube`, `tiktok`, `instagram`, `x`, and others.                                                                      |
| `min_followers` / `max_followers`      | integer | Follower-count floor / ceiling.                                                                                                                 |
| `follower_bucket`                      | array   | Audience-size bands (e.g. `100k_300k`). With `categories`, enables filter-only browse. Mutually exclusive with `min_followers`/`max_followers`. |
| `creator_country` / `audience_country` | string  | Where the creator / their audience is based (ISO 3166-1 alpha-2).                                                                               |
| `creator_language`                     | string  | Creator's primary language, e.g. `en`.                                                                                                          |
| `has_email`                            | boolean | Only creators that have (or lack) a public email.                                                                                               |
| `limit`                                | integer | 1–25 (default 10).                                                                                                                              |
| `cursor`                               | string  | Pass a previous response's `next_cursor` to page filter-only browse.                                                                            |

**`creator_get`** — get one creator's full profile by Upriver `creator_id` or channel URL.

| Parameter | Type                  | Description                                                                                                                                                                            |
| --------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `creator` | string · **required** | An Upriver `creator_id` (UUID) or a full channel URL (e.g. `https://youtube.com/@handle`). A bare `@handle` isn't accepted — resolve it with `creator_search` first.                   |
| `include` | array                 | Optional enrichments. Fast: `engagement_metrics`, `video_metrics`, `relative_metrics`, `email`. Slower (live research): `bio`, `audience`, `brand_safety`. Request only what you need. |

Returns the profile (channels, categories, related creators) plus any requested enrichments.

## Access

Upriver MCP access is provisioned per account. Request access at [dashboard.upriver.ai](https://dashboard.upriver.ai) or email [support@upriver.ai](mailto:support@upriver.ai). Once your account is enabled, the same Upriver sign-in (or API key) works across every MCP client — find your API key in the [Upriver dashboard](https://dashboard.upriver.ai).

## Troubleshooting

| Symptom                                                 | Fix                                                                                                          |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| "MCP access isn't enabled for this Upriver account yet" | Your account isn't provisioned yet — request access at [dashboard.upriver.ai](https://dashboard.upriver.ai). |
| Prompted to sign in, or `401`                           | Complete the OAuth sign-in, or check that your `X-API-Key` header is set and valid.                          |
| Tools don't appear after connecting                     | Reconnect and re-list tools. Make sure the transport is **Streamable HTTP**, not SSE.                        |
| Claude or ChatGPT shows no API-key field                | Those connector UIs are OAuth-only — use **Sign in with Upriver** instead.                                   |
| JetBrains IDE won't connect                             | Not supported yet (the IDE drops custom headers and lacks OAuth for remote servers).                         |

## More on the way

Breakout topics and creators are the first of Upriver's capabilities to land as MCP tools. The rest of the API — audiences, brands, products, trends, and sponsorships — is documented in the [API reference](/), and we're rolling those out as MCP tools too.

<CardGroup cols={2}>
  <Card title="Dashboard" icon="gauge" href="https://dashboard.upriver.ai">
    Request access and manage your account
  </Card>

  <Card title="skill.md" icon="lobster" href="/ai/skillmd">
    Give agents the full Upriver API reference
  </Card>
</CardGroup>