Upriver MCP
Real-time context on creators, audiences, brands, trends, and sponsorships — for AI applications.
## About Upriver
[Upriver](https://upriver.ai) 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
| | |
|---|---|
| **Endpoint** | `https://mcp.upriver.ai/mcp` |
| **Transport** | Streamable HTTP |
| **Auth** | Sign in with Upriver (OAuth), or send your Upriver API key in the `X-API-Key` header |
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)
```bash
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
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:
```json
{ "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**):
```json
{ "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:
```json
{ "mcpServers": { "upriver": { "type": "streamableHttp", "url": "https://mcp.upriver.ai/mcp" } } }
```
### Windsurf
Edit `~/.codeium/windsurf/mcp_config.json` — Windsurf's field is **`serverUrl`**:
```json
{ "mcpServers": { "upriver": { "serverUrl": "https://mcp.upriver.ai/mcp" } } }
```
More clients — Codex CLI, ChatGPT, Goose, Zed
**Codex CLI (OpenAI)**
```bash
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
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
{ "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`](./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.
| 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).
## 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](https://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](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.
## 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](./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](https://upriver.ai/terms). 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.