> For the complete documentation index, see [llms.txt](https://docs.upriverdata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.upriverdata.com/product-usage/agent/mcp.md).

# Upriver MCP

Use the Upriver agent from Claude, Codex, Cursor and other AI clients through MCP.

The Upriver MCP server brings the Upriver [Agent](/product-usage/agent.md) into the AI clients you already use, such as Claude, Codex and Cursor.

Your client sends your request to Upriver. The agent does the work with its full context of your data stack, and your client gets the answer back with a link to the task in Upriver.

You don't have to give your client any context about your data, and you don't have to build your own MCP servers or skills for it. Upriver already knows your schemas, lineage, pipelines and business definitions.

## How it works

* Each request from your client starts or continues an Upriver **task**. It is the same kind of task you see in the Upriver web app.
* Every task that you start through MCP shows in your task list in the web app. You can open it there to see the full tables, charts and steps, or to continue the work.
* When the agent needs a decision from you, your client shows its question. Your answer goes back to the same task.

## Server URL

```
https://agentic-eks-api-server.upriverdata.com/upriver-mcp/
```

The server uses the streamable HTTP transport. If your Upriver workspace is in the EU region, contact Upriver support for your server URL.

## Authentication

Add the server URL to your client. The first time your client connects, it opens a browser window where you sign in to Upriver. Your client then acts as you, with the same access that you have in the Upriver web app. You don't have to copy a token.

## Connect your client

### Let your agent set it up (recommended)

The fastest way is to ask your AI client to do it. Paste this message into Claude Code, Codex or Cursor:

```
Set up the Upriver MCP server for me. Follow the instructions at https://docs.upriverdata.com/product-usage/agent/mcp
```

Your client reads this page and adds the server. Then sign in to Upriver when your client asks.

### Or pick your client

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Add to Cursor</strong></td><td>One click adds the server to Cursor</td><td><a href="https://875415170-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLE0zsJmUpeLjYw085cnO%2Fuploads%2Fgit-blob-7b0974d0afdd5a620305319bef11c5941a4143d3%2Fmcp-cursor.svg?alt=media">mcp-cursor.svg</a></td><td><a href="https://cursor.com/install-mcp?name=upriver&#x26;config=eyJ1cmwiOiJodHRwczovL2FnZW50aWMtZWtzLWFwaS1zZXJ2ZXIudXByaXZlcmRhdGEuY29tL3Vwcml2ZXItbWNwLyJ9">https://cursor.com/install-mcp?name=upriver&#x26;config=eyJ1cmwiOiJodHRwczovL2FnZW50aWMtZWtzLWFwaS1zZXJ2ZXIudXByaXZlcmRhdGEuY29tL3Vwcml2ZXItbWNwLyJ9</a></td></tr><tr><td><strong>Add to Claude</strong></td><td>Open Connectors in Claude and add a custom connector</td><td><a href="https://875415170-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLE0zsJmUpeLjYw085cnO%2Fuploads%2Fgit-blob-886307c8b75ed697dc1e4f081f4dee2601e18dcc%2Fmcp-claude.svg?alt=media">mcp-claude.svg</a></td><td><a href="https://claude.ai/customize/connectors">https://claude.ai/customize/connectors</a></td></tr><tr><td><strong>Claude Code</strong></td><td>Run one command</td><td><a href="https://875415170-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLE0zsJmUpeLjYw085cnO%2Fuploads%2Fgit-blob-886307c8b75ed697dc1e4f081f4dee2601e18dcc%2Fmcp-claude.svg?alt=media">mcp-claude.svg</a></td><td><a href="#claude-code">#claude-code</a></td></tr><tr><td><strong>Codex CLI</strong></td><td>Run one command</td><td><a href="https://875415170-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLE0zsJmUpeLjYw085cnO%2Fuploads%2Fgit-blob-d4ddb88938a6096fc7401497f846037dd36fbf6e%2Fmcp-codex.svg?alt=media">mcp-codex.svg</a></td><td><a href="#codex">#codex</a></td></tr><tr><td><strong>Codex desktop</strong></td><td>Opens a new Codex chat with the setup message</td><td><a href="https://875415170-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLE0zsJmUpeLjYw085cnO%2Fuploads%2Fgit-blob-d4ddb88938a6096fc7401497f846037dd36fbf6e%2Fmcp-codex.svg?alt=media">mcp-codex.svg</a></td><td><a href="codex://threads/new?prompt=Set%20up%20the%20Upriver%20MCP%20server%20for%20me.%20Follow%20the%20instructions%20at%20https%3A%2F%2Fdocs.upriverdata.com%2Fproduct-usage%2Fagent%2Fmcp">codex://threads/new?prompt=Set%20up%20the%20Upriver%20MCP%20server%20for%20me.%20Follow%20the%20instructions%20at%20https%3A%2F%2Fdocs.upriverdata.com%2Fproduct-usage%2Fagent%2Fmcp</a></td></tr></tbody></table>

### Claude Code

Run this command, then run `/mcp` in Claude Code and select **upriver** to sign in:

```bash
claude mcp add --scope user --transport http upriver https://agentic-eks-api-server.upriverdata.com/upriver-mcp/
```

`--scope user` makes Upriver available in all your projects.

### Claude Desktop and claude.ai

1. Go to **Customize** → **Connectors**, or open [claude.ai/customize/connectors](https://claude.ai/customize/connectors).
2. Click **+ Add** → **Add custom connector**.
3. Enter the name `Upriver` and the server URL.
4. Click **Connect** and sign in to Upriver.

A connector that you add on claude.ai is also available in Claude Desktop when you sign in with the same account.

### Codex

The Codex CLI and the Codex desktop app use the same settings, so you only need to set this up once.

**Codex desktop:** click the **Codex desktop** card above. It opens a new Codex chat with the setup message. Send the message, and Codex adds the server for you.

**Codex CLI:** run this command. It adds the server and opens a browser window where you sign in to Upriver:

```bash
codex mcp add upriver --url https://agentic-eks-api-server.upriverdata.com/upriver-mcp/
```

To sign in again later, run `codex mcp login upriver`.

### Cursor

Add the server to `~/.cursor/mcp.json` (for all projects) or to `.cursor/mcp.json` (for one project):

```json
{
  "mcpServers": {
    "upriver": {
      "url": "https://agentic-eks-api-server.upriverdata.com/upriver-mcp/"
    }
  }
}
```

Then open **Cursor Settings** → **MCP** and sign in to **upriver**. Cursor shows the results as text. It does not show the live task view.

### Other clients

Other clients that support remote MCP servers over streamable HTTP with OAuth sign-in can also connect. Add the server URL in the client's MCP settings, then sign in to Upriver when the tool asks.

The live task view shows only in clients that support MCP Apps. Other clients show the results as text.

## Check the connection

Ask your client a question about your data, for example:

> Ask Upriver what data sources are connected.

Your client calls Upriver and returns the agent's answer with a link to the task in the Upriver web app.

## Live view

In clients that support MCP Apps, such as Claude and Codex, Upriver shows a live view of the task inside the chat instead of a text-only reply. The view shows the agent's steps as it works, any question it needs you to answer, and the final answer with its tables and charts.

You don't have to set anything up. Clients that support MCP Apps show the live view automatically. Other clients, such as Cursor, show the results as text.

## Considerations

* **Permissions:** your client acts as you, with the same access that you have in the Upriver web app. The agent has read-only access to your warehouse.
* **Result size:** to keep your client's context small, answers summarize query results instead of including every row. Your client can get up to 200 rows for each query with `get_query_results`. The full results are in the Upriver web app.
* **Tasks:** every question that you ask through MCP is saved as a task in your Upriver task list, so you can open it in the web app later.

## Next steps

* [MCP tools reference](/product-usage/agent/mcp/mcp-tools.md): the tools that the server gives your AI client.
* [Agent](/product-usage/agent.md): what the Upriver agent can do.