MCP Server - Upriver API Docs

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).

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.

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

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.

claude mcp add --transport http upriver https://mcp.upriver.ai/mcp

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

claude mcp add --transport http upriver https://mcp.upriver.ai/mcp \
  --header "X-API-Key: YOUR_UPRIVER_API_KEY"

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project), then connect it in Settings → Tools & Integrations to sign in:

{ "mcpServers": { "upriver": { "url": "https://mcp.upriver.ai/mcp" } } }

For API-key auth, add "headers": { "X-API-Key": "YOUR_UPRIVER_API_KEY" }.

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

{ "servers": { "upriver": { "type": "http", "url": "https://mcp.upriver.ai/mcp" } } }

For API-key auth, add "headers": { "X-API-Key": "YOUR_UPRIVER_API_KEY" }.

In Claude, go to Customize → Connectors → ”+” → Add custom connector, name it Upriver, paste https://mcp.upriver.ai/mcp, then Connect and sign in.

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.

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:

{ "mcpServers": { "upriver": { "type": "streamableHttp", "url": "https://mcp.upriver.ai/mcp" } } }

Edit ~/.codeium/windsurf/mcp_config.json — Windsurf’s field is serverUrl:

{ "mcpServers": { "upriver": { "serverUrl": "https://mcp.upriver.ai/mcp" } } }

More clients — Codex CLI, ChatGPT, Goose, Zed

Codex CLI (OpenAI)

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:

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:

{ "context_servers": { "upriver": { "url": "https://mcp.upriver.ai/mcp", "headers": { "X-API-Key": "YOUR_UPRIVER_API_KEY" } } } }

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.

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 or email 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.

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.
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.

Dashboard

Request access and manage your account

skill.md

Give agents the full Upriver API reference

​Connect

​Tools available today

​Breakout topics

​Creators

​Access

​Troubleshooting

​More on the way

Dashboard

skill.md

Connect

Tools available today

Breakout topics

Creators

Access

Troubleshooting

More on the way