River MCP · Docs

Connect your AI assistant to River

River works with Claude Code, Codex, Cursor, VS Code, Claude, ChatGPT, and any AI assistant that supports MCP. Install River, add it to your assistant, sign in with a code River emails you, and your assistant can hand River real work.

How it works

River is an AI workspace with its own browser and apps. River’s AI works there, in its own desktops and windows, never on your screen. River’s MCP server lets your assistant see everything in your River, ask River’s AI to do the work, make quick changes itself, and move files in and out.

Assistants on your computer, like Claude Code, Codex, and Cursor, add River’s connector app, a small MCP server that runs on your computer. Chat apps like Claude and ChatGPT add River’s address as a custom connector.

The quickest way: paste this into your assistant, and it walks you through the rest.

Set up River for me. River is my AI workspace: its AI works in River's own browser and apps, and you can hand it work through River's MCP server.

1. Add River's MCP server, named "river". It runs on this computer: npx -y @meetriver/mcp
   Claude Code: claude mcp add river -- npx -y @meetriver/mcp
   Can't run it here (Claude.ai, ChatGPT)? Add https://api.meetriver.com/mcp as a custom connector instead, and I'll sign in on River's page.
   If River's tools don't show up, ask me to restart you and paste this again.
2. Call River's sign_in tool with no arguments and follow it. It checks that River is installed, then has you ask me for my email and the code River emails me.
3. Call get_workspace and follow River's setup guide.

Docs: https://meetriver.com/mcp/docs

Get River

Download River for Mac, Windows, or Linux, open it, and sign up. Remember the email you use: your assistant asks for it. Signing in from an assistant never makes a new account.

River opens when your computer starts and keeps running in the background, even with no window open. That’s how your assistant can hand it work any time, including work on sites you’re signed in to in River’s browser. Closing River’s window keeps it running; to change whether it starts with your computer, use Open River when you start your computer in River’s Settings.

Connect your assistant

Claude Code

claude mcp add river -- npx -y @meetriver/mcp

Then start a new Claude Code session so River’s tools load.

Codex

codex mcp add river -- npx -y @meetriver/mcp

Cursor, Windsurf, Claude Desktop, and Gemini CLI

Add this to ~/.cursor/mcp.json for Cursor, ~/.codeium/windsurf/mcp_config.json for Windsurf, claude_desktop_config.json for Claude Desktop, or ~/.gemini/settings.json for Gemini CLI, then restart the app.

{
  "mcpServers": {
    "river": {
      "command": "npx",
      "args": ["-y", "@meetriver/mcp"]
    }
  }
}

VS Code

Add this to .vscode/mcp.json.

{
  "servers": {
    "river": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@meetriver/mcp"]
    }
  }
}

Claude and ChatGPT

Chat apps can’t run River’s connector app, so they add River’s address. In Claude, open Settings, then Connectors, and choose Add custom connector. In ChatGPT, adding your own connector uses Developer mode, in Settings. Name it River and paste this address:

https://api.meetriver.com/mcp

A River window opens: enter the email you signed up with and the code River sends you, then allow access. Your plan or your workspace’s admin decides whether custom connectors are available.

Any other assistant

Add npx -y @meetriver/mcp as a local (stdio) MCP server named river. It needs Node.js 18 or later. If your assistant only takes remote servers, add River’s address instead. If River’s tools don’t show up, restart your assistant or start a new session.

Once River is added, ask your assistant to sign you in. It calls River’s sign_in tool, which goes like this:

River checks this computer. If River isn’t installed, your assistant gives you the download link. Install River, sign up, and tell your assistant.
Your assistant asks for your email, the one you signed up to River with. River emails you a 6-digit code. If the email says there’s no River account for that address, sign up in River with it, or give the email you did use.
You give your assistant the code. It works for 10 minutes. River’s tools appear in your assistant right away.

You sign in once for each assistant, and it stays signed in. The email names the assistant that asked and has a Remove access link. The sign-in is saved for your user only, in ~/.config/river/mcp.json(%APPDATA%\river\mcp.json on Windows).

Working with River

Most work follows the same loop. Here it is with the tool your assistant uses at each step.

Bring in what River needs. Notes, a spreadsheet, or a file from your computer go into River with upload. Anything already in River can be found with search and read.
Ask River. send_message starts a chat with River’s AI. Say the outcome and who it’s for, and attach the items it needs: “Find 20 heads of operations at Series A fintechs and add them to a Leads sheet, each with a reason to write now.”
Check in. get_chat shows River’s progress, its questions, and what it made. Research or a deck often takes 3 to 15 minutes, and River keeps going if your assistant stops checking. When River asks something, your assistant answers with answer or decide, or asks you.
Shape it. Ask for changes in the same chat with send_message: “Drop anyone at a company under 20 people.” River reads it at its next step. screenshot shows a window or page as a picture.
Work on the web. River’s AI uses River’s own browser, signed in to the sites you’ve signed in to there, as long as River is running on your computer. It fills in forms, updates your CRM, and sends from your accounts when you ask it to.
Take it with you. export gets any document, sheet, or deck as a file, like PDF, Word, Excel, or PowerPoint. Every result also has a link that opens it in River.

You can open River any time to watch: every chat your assistant starts shows in River, with each step in the chat and the work in River’s windows. Type in the chat to steer it, or stop it.

What only you do

Your assistant does the rest, and hands each of these to you:

Installing River and signing up. In River’s app, on your computer.
Signing in. You give your assistant your email and the code River emails you, or enter them on River’s own sign-in page.
Paying. If you choose a paid plan, your assistant gives you a payment link. Only a workspace’s owner or an admin can pay.
Connecting your accounts. For Gmail, Google Calendar, Slack, and others, your assistant gives you a link to approve on that service’s page.
Files only you have. Your assistant can give you a link to a River page where you add them from your device.
Questions only you can answer. When River asks something your assistant can’t know, it passes the question on.

What your assistant can do

Once you’re signed in, your assistant sees these tools. Each answer says what happened, gives links that open items in River, and suggests what to do next. River’s connector app adds one more, sign_in.

Tool	What it does
`get_workspace`	Your account, plan and AI allowance, whether River is installed and running on your computer, what to set up next, your desktops and open windows, the chats River is working on, and what changed.
`switch_workspace`	Moves to another River workspace you belong to.
`read`	Reads any item, folder, setting, connected account, task, project, or guide, all in one tree.
`search`	Finds items, chats, and synced email and records by meaning.
`screenshot`	Shows a desktop, a window, a page of an item, or the page River’s browser is on in a chat, as a picture.
`send_message`	Asks River’s AI to do something, in a new chat or one already going.
`get_chat`	Follows a chat: River’s progress, its replies and questions, and what it made. Also lists your chats.
`answer`	Answers River’s questions and connection offers.
`decide`	Approves or declines what River is waiting to do, with a note if needed.
`stop_chat`	Stops River in a chat. The chat can pick up again later.
`use_tool`	Runs one of River’s tools directly, like adding a row or creating a calendar event.
`upload`	Brings files into River: small files directly, big files in parts, or through a link where you add them.
`export`	Gets an item as a file, like PDF, Word, Excel, or PowerPoint, or a folder as a zip.
`get_billing`	Shows your plan, what’s left of this month’s AI allowance, and every plan’s price.
`create_payment_link`	Makes a link for you to pay for a plan or an add-on.

use_tool reaches River’s apps: documents, sheets, slides, notes, tasks, calendar, Drive, memory, connections, and more. Your assistant can list them all with read({"path": "tools/"}).

Sending, sharing, and buying

Anything that reaches other people, like email, messages, invitations, sharing, publishing, or orders, goes through River’s AI, never a direct tool call. River’s guide tells your assistant to ask for these only when you asked, and to approve only what you asked for, exactly.

When River needs a decision before it goes ahead, your assistant sees an approval card and approves or declines it with decide.

Files

Your assistant can bring in files it has: small ones directly, and big ones in parts. CSV and Excel files can become Sheets, and documents can become Docs. For files only you have, it gives you a link to a page where you add up to 100 MB at a time. The link lasts 24 hours.

To take work out, it exports items as files: documents as PDF, Word, or Markdown; sheets as Excel, CSV, or PDF; presentations as PDF or PowerPoint; and folders as a zip. Download links last 24 hours.

Plans and billing

Working through your assistant uses your River plan and its monthly AI allowance, just like working in River. Your assistant can show your plan and what’s left, and give you a link to pay. River’s plans and prices

Teams and workspaces

Your assistant works in one River workspace at a time. It can do what you can do there, and nothing more. If you belong to more than one, it can see which one it’s in and switch to another.

Removing access

Open the Remove access link in the email River sent with the code, and confirm. That assistant can’t use your River anymore, and your work stays as it is.

If something goes wrong

What you see	What to do
River’s tools don’t show up	Restart your assistant or start a new session.
Your assistant says River isn’t installed	Download River, open it, and sign up, then tell your assistant.
River’s email says there’s no account	Sign up in River’s app with that email, or give your assistant the email you signed up with.
Your assistant says it needs to sign in	Ask it to sign you in again, or reconnect River in your assistant’s connector settings.
The code doesn’t work	Codes work for 10 minutes. Ask your assistant for a new one.
River can’t use a site you’re signed in to	Open River on your computer. It keeps running in the background after that.
River needs a plan	Your assistant can give you a payment link, or you can wait for next month’s allowance.
A service isn’t connected	Your assistant can give you a link to connect it.

For AI assistants

If you’re an AI assistant setting River up for your person:

Add River’s MCP server, named river: the local command npx -y @meetriver/mcp (for example claude mcp add river -- npx -y @meetriver/mcp). If you can’t run local servers, add https://api.meetriver.com/mcp as a remote (Streamable HTTP) server and have your person sign in on River’s page. If the tools don’t appear, ask your person to restart you.
Call sign_in with no arguments and follow its result. If River isn’t installed, give your person the download link it returns. Then ask for the email they signed up to River with, call sign_in({"email": "…"}), ask for the 6-digit code, and call sign_in({"email": "…", "code": "…"}).
Call get_workspace. It lists what to set up next, with the call that does it.
Read River’s guides: read({"path": "guides/start-here"}), then guides/setting-up and guides/errors.
Use send_message for work that takes judgment or several steps, for work on websites, and for anything that reaches other people; follow it with get_chat until it’s done. Use use_tool for one precise action.
Pass each for_person link to your person with its sentence. Ask River to send, share, publish, or buy only what your person asked for.