> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryvo.so/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect Claude Code, Cursor, VS Code or Windsurf to your Ryvo account with the same API keys you already use.

<div style={{ position: "relative", paddingBottom: "56.25%", height: 0 }}>
  <iframe src="https://cap.so/embed/y8cfsk3a2k9sbhb" title="Ryvo MCP server" frameBorder="0" allow="fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }} />
</div>

Ryvo runs a remote [Model Context Protocol](https://modelcontextprotocol.io) server. Connect it to your AI coding assistant and you can ask, in plain language, things like "how many calls failed yesterday and why?", "create an agent for appointment reminders" or "show me the last conversation with this number", without writing code against the API.

| | |
| - | - |
| URL | `https://mcp.ryvo.so` (also answers at `https://mcp.ryvo.so/mcp`) |
| Transport | Streamable HTTP, stateless: no sessions to keep alive |
| Protocol | MCP `2026-07-28`, with fallback for clients on the 2025 revisions |
| Authentication | `Authorization: Bearer ryvo_live_...` |
| Plan | Starter or higher, like the [API](/authentication) |

The server does not reimplement the API: each tool runs the same endpoint of the [public API](/api-reference) inside our servers, with your key and your IP. Same data, same scopes, same errors, same rate limits, same credit limit.

## Before you start

You need an **API key**. There is no separate MCP credential: it is the same `ryvo_live_...` key you create in **Settings > API keys** ([app.ryvo.so/developers](https://app.ryvo.so/developers)). See [Authentication](/authentication) for how to create one.

Create **one key just for the MCP** and choose its scopes with care:

* The assistant only sees the tools its scopes allow. A read-only key does not even see `create_call`. The full list is in [Tools](/mcp/tools).
* In **Advanced configuration**, set a **Credit limit**. It is the real protection against an agent that spends more than you meant: read [Security and spending](/mcp/security).
* If the assistant will read transcripts without you watching, give it a read-only key. [Here is why](/mcp/security#transcripts-are-untrusted-content).

Then put the key in an environment variable instead of pasting it into a config file:

```bash theme={null}
export RYVO_API_KEY="ryvo_live_..."
```

## Connect your client

<Tabs>
  <Tab title="Claude Code">
    For a project, add a `.mcp.json` file at its root. Claude Code expands `${RYVO_API_KEY}` from your environment when it starts, so the file holds no secret and you can commit it:

    ```json .mcp.json theme={null}
    {
      "mcpServers": {
        "ryvo": {
          "type": "http",
          "url": "https://mcp.ryvo.so",
          "headers": {
            "Authorization": "Bearer ${RYVO_API_KEY}"
          }
        }
      }
    }
    ```

    Or add it from the terminal, for yourself only:

    ```bash theme={null}
    claude mcp add --transport http ryvo https://mcp.ryvo.so \
      --header "Authorization: Bearer $RYVO_API_KEY"
    ```

    Here your shell expands the variable, so the key itself is saved in your Claude Code configuration. Add `--scope user` to have Ryvo in all your projects.
  </Tab>

  <Tab title="Cursor">
    Edit `~/.cursor/mcp.json` (all your projects) or `.cursor/mcp.json` (one project). Cursor reads `${env:RYVO_API_KEY}` from your environment:

    ```json mcp.json theme={null}
    {
      "mcpServers": {
        "ryvo": {
          "url": "https://mcp.ryvo.so",
          "headers": {
            "Authorization": "Bearer ${env:RYVO_API_KEY}"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add `.vscode/mcp.json` to your workspace. With an `inputs` entry, VS Code asks for the key the first time the server starts, hides what you type and stores it securely:

    ```json .vscode/mcp.json theme={null}
    {
      "inputs": [
        {
          "type": "promptString",
          "id": "ryvo-api-key",
          "description": "Ryvo API key",
          "password": true
        }
      ],
      "servers": {
        "ryvo": {
          "type": "http",
          "url": "https://mcp.ryvo.so",
          "headers": {
            "Authorization": "Bearer ${input:ryvo-api-key}"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Windsurf is now **Devin Desktop**, and its default agent (Devin Local) reads MCP servers from `~/.config/devin/mcp_config.json` (on Windows, `%APPDATA%\devin\mcp_config.json`). For one project, use `.devin/mcp_config.json`, or `.devin/mcp_config.local.json` to keep it out of git. It reads `${env:RYVO_API_KEY}` from your environment:

    ```json mcp_config.json theme={null}
    {
      "mcpServers": {
        "ryvo": {
          "url": "https://mcp.ryvo.so",
          "transport": "http",
          "headers": {
            "Authorization": "Bearer ${env:RYVO_API_KEY}"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other clients">
    Any MCP client that speaks Streamable HTTP and lets you set a request header works. Give it:

    * URL: `https://mcp.ryvo.so`
    * Header: `Authorization: Bearer ryvo_live_...`
  </Tab>
</Tabs>

<Info>
  Coming soon: the Ryvo CLI (`@ryvo-so/cli`) will write this configuration for you with `ryvo mcp install`.
</Info>

## Clients that are not supported yet

Version 1 authenticates **only with a header**. There is no OAuth sign-in yet, so clients that add remote servers only through an OAuth connector cannot connect: that includes **claude.ai connectors** and **ChatGPT**. OAuth is planned for a later phase.

For the same reason, a missing or wrong key gets a plain `401` with the JSON error of the API, without a `WWW-Authenticate` header pointing to OAuth metadata: your client shows the error instead of opening a sign-in page that does not exist.

## Check the connection

1. Restart your client or reload its MCP servers (in Claude Code, `/mcp` shows the status of each one).
2. Ask the assistant to "call `get_account`". It answers with your account, your plan and the scopes the key carries. For your credit balance, `get_billing_summary` (needs `billing:read`).
3. If the server does not connect, test the key on its own with `curl https://api.ryvo.so/v1/me -H "Authorization: Bearer $RYVO_API_KEY"`. A `401` means the key is wrong or revoked, or the header is not written as `Bearer ` plus the key.

If a tool you expected is missing, the key lacks its scope: compare with the table in [Tools](/mcp/tools).