ai.upriver/upriver

About Upriver

Upriver provides an API that turns what's happening online into real-time, reliable context for AI applications. It delivers evidence-backed signals — each grounded in real sources — across:

• Creators — relevant creators and profiles
• Audiences — personas, interests, language, and humor
• Brands — brands and how they're being discussed
• Products — product mentions and use cases
• Trends — topics and formats gaining attention
• Sponsorships — brand–creator relationships and placements

This repository is the home of Upriver's Model Context Protocol (MCP) server, which brings that context to any MCP-compatible AI assistant or agent.

Connect

It's a remote, hosted server — nothing to install or run. 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 Code (CLI)

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"

Cursor

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 (GitHub Copilot)

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

Claude Desktop & claude.ai

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, and don't add a raw url entry to claude_desktop_config.json; the desktop app rejects it.)

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:

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

Windsurf

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

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

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" } } } }

Any other MCP client

Most clients use the Cursor shape above (mcpServers + url, optional headers). For agents that read install manifests, see llms-install.md.

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

The MCP server currently exposes Upriver's breakout topics — emerging subjects gaining traction online across tech, sports, and politics, each returned with grounded source citations so the model reasons from real evidence instead of guessing.

Both tools are read-only. Each returns up to limit topics (default 10, max 25), every topic carrying up to 5 source citations, plus a has_more flag when more topics exist beyond the page.

breakout_search_topics

Search breakout topics by keyword.

breakout_list_topics

Browse breakout topics gaining traction right now.

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

More on the way

Breakout topics are the first slice of the Upriver API to land as MCP tools. The full API — Creators, Audiences, Brands, Products, Trends, and Sponsorships — is documented at docs.upriver.ai, and we're rolling those endpoints out as MCP tools. Watch this repository for new tools as they ship.

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.

Links

• Docs — https://docs.upriver.ai
• Dashboard — https://dashboard.upriver.ai
• Website — https://upriver.ai

License

The contents of this repository — connection documentation and listing metadata — are released under the MIT License.

The hosted Upriver MCP service and the Upriver API are operated by Potato Laboratories, Inc. d/b/a Upriver and are governed by Upriver's Terms of Service. The MIT License covers this repository only — not the service, nor the data it returns. "Upriver" and the Upriver logo are trademarks of Potato Laboratories, Inc. and are not covered by the MIT License.