# Upriver Mcp

> Know what's gaining traction online: breakout topics in tech, sports & politics, with citations.

- **Type:** MCP server
- **Install:** `agentstack add mcp-upriver-ai-upriver-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [upriver-ai](https://agentstack.voostack.com/s/upriver-ai)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [upriver-ai](https://github.com/upriver-ai)
- **Source:** https://github.com/upriver-ai/upriver-mcp

## Install

```sh
agentstack add mcp-upriver-ai-upriver-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [upriver-ai](https://github.com/upriver-ai)
- **Source:** [upriver-ai/upriver-mcp](https://github.com/upriver-ai/upriver-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-upriver-ai-upriver-mcp
- Seller: https://agentstack.voostack.com/s/upriver-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.