---
title: "MCP server"
description: "Connect Claude Code and other MCP clients to your mentions. Sign in with OAuth or use an API key."
canonical: https://docs.rumoro.dev/mcp
markdown: https://docs.rumoro.dev/mcp.mdx
---

# MCP server

Connect Claude Code and other MCP clients to your mentions. Sign in with OAuth or use an API key.

Rumoro's [Model Context Protocol](https://modelcontextprotocol.io) server is hosted, so there is nothing to install. Once your MCP client is connected, your agent can search and triage mentions, manage keywords and your company profile, read analytics, and set up alerts, people and segments. It follows the same rules as the dashboard.

```
https://mcp.rumoro.dev/mcp
```

- **Hosted, streamable HTTP, no session.** There is nothing to install. Clients must accept both `application/json` and `text/event-stream` answers.
- **OAuth or an API key.** Clients that support MCP authorization sign you in through the browser. Others send a key as a Bearer header. With `read` access the client sees only the read tools, with `write` it sees all.
- **55 tools** that match the [REST API](/conventions). They are listed under [Tools](/mcp/tools).

## Quick start

<Steps>
  <Step>
    ### Add the server

    In Claude Code, run

    ```bash
    claude mcp add --transport http rumoro https://mcp.rumoro.dev/mcp
    ```

    Then type `/mcp`, choose `rumoro` and **Authenticate**. Sign in and approve the access the client asks for. If you belong to several workspaces, you also choose one. Other clients are under [Installation](#installation).

    For CI, a server or a client without OAuth, create a key on the **API keys** page, `read` to look around or `write` to make changes. You only see it once.
  </Step>

  <Step>
    ### Ask

    Try "Which mentions this week were negative, and what were people unhappy about?"
  </Step>
</Steps>

## Authentication

Each tool call carries a Bearer credential. The server handles both kinds the same way.

```
Authorization: Bearer <OAuth access token>
Authorization: Bearer ref_...
```

### OAuth 2.1

Sign-in follows the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization). A call without a credential gets `401` with `WWW-Authenticate: Bearer realm="rumoro-mcp", resource_metadata="https://mcp.rumoro.dev/.well-known/oauth-protected-resource"`. The client then registers itself (dynamic registration with PKCE) and opens the browser. You approve each sign-in on a consent page, and the token acts as you, within your role in that workspace. Access tokens last an hour. With `offline_access` the client also gets a refresh token that lasts 30 days and is replaced each time it is used. A sign-in without `write` works as `read`.

### API keys

Create keys on the **API keys** page or with [`POST /v1/api-keys`](/authentication). You see each key once, and it belongs to one workspace. When you revoke a key, the client stops working at its next call.

### Discovery

Connecting needs no credential. `initialize`, `tools/list` and the resources answer without one. A credential that is sent is always checked, and every `tools/call` needs one.

<Callout title="claude.ai, Claude Desktop and ChatGPT">
  Add `https://mcp.rumoro.dev/mcp` as a custom connector and sign in when asked.
</Callout>

## Resources

| Resource | URI | What it contains |
| --- | --- | --- |
| `openapi` | `https://api.rumoro.dev/v1/openapi.json` | The REST API behind the tools, with all schemas |
| `agent-guide` | `https://mcp.rumoro.dev/mcp/guide` | How an agent connects, what each permission allows, and a review workflow |

Each tool has `readOnlyHint`, `destructiveHint` and `idempotentHint`, so a client knows which calls to confirm first. The seven destructive tools are marked under [Tools](/mcp/tools).

Registries can read the [server card](https://mcp.rumoro.dev/.well-known/mcp/server-card.json).

## How the tools behave

- Each tool runs the same operation as the REST API, with the same validation, errors and [rate limit](/rate-limits).
- `search_mentions` returns 10 mentions by default and `hasMore`, without a cursor. When there are more, narrow the filters or the time range.
- There are no export tools. Use the REST exports or the [CLI](/cli) for large lists.
- Write tools need a `write` key or sign-in. With `read` they don't appear at all.
- The server keeps no session between requests. Answers come as JSON or as a short event stream.

## Author data

`list_people`, `get_person` and the other people tools return the public facts Rumoro keeps about authors, such as name, handle, picture, follower count and profile details. They never return an email address, so `profile.email` is always `null` over MCP, even where the REST API shows one. [How it works](/how-it-works#author-data) explains what is stored and how people can ask to be removed.

## What you can ask

- "Summarise what people said about us on Hacker News and Reddit in the last 7 days."
- "Find questions about our pricing that nobody has answered, and draft a reply for each."
- "Which competitor got the most positive mentions this month, and why?"
- "Mark every mention from our own team as done."
- "Our keyword `driftwood` is noisy. Look at its health report and apply the best suggestion."
- "Create a daily digest of negative mentions for the support channel at 9:00 Berlin time."
- "Who are the people with more than 10,000 followers who mentioned us this month?"

## Documentation MCP server

The docs have their own read-only MCP server, and it needs no key.

```
https://docs.rumoro.dev/api/mcp
```

- **Tools.** `search_docs` searches the full text, `read_page` returns a page as Markdown by its path, such as `/quickstart`, and `list_pages` lists every page with its title and description.
- **Resources.** Every page at its `.mdx` address, plus `https://docs.rumoro.dev/llms.txt`.
- **Card.** [`/.well-known/mcp.json`](https://docs.rumoro.dev/.well-known/mcp.json).

## Security

- **Give only the access needed.** Use `read` to explore, and `write` only for an agent that should change things. No tool can change billing or API keys, though `get_usage` and `list_ledger` read the balance.
- **Same rules as the API.** Calls act as the key's workspace or the person who signed in, with the same checks and [rate limit](/rate-limits).
- **Keep keys out of repositories.** OAuth leaves no secret in client settings. With a key, use user-level settings or an environment variable, and revoke it if it leaks.

## Installation

With OAuth, a client only needs the URL. With a key, add the `Authorization: Bearer ref_...` header. In the [CLI](/cli), `rumoro mcp:config` prints these settings with your key filled in.

<Accordions type="multiple">
  <Accordion title="Claude Code" id="claude-code">
    ```bash
    claude mcp add --transport http rumoro https://mcp.rumoro.dev/mcp
    ```

    Then run `/mcp`, choose `rumoro` and **Authenticate**. Add `--scope project` to save the URL in the repository's `.mcp.json`, or `--scope user` to use it in every project. The [Claude Code page](https://rumoro.dev/claude) walks through it with example questions. With a key, run

    ```bash
    claude mcp add --transport http rumoro https://mcp.rumoro.dev/mcp \
      --header "Authorization: Bearer ref_..."
    ```
  </Accordion>

  <Accordion title="Cursor" id="cursor">
    Add the server to `~/.cursor/mcp.json` for every project, or to `.cursor/mcp.json` for one. The [Cursor page](https://rumoro.dev/cursor) walks through it with example questions.

    ```json title=".cursor/mcp.json"
    {
      "mcpServers": {
        "rumoro": {
          "url": "https://mcp.rumoro.dev/mcp",
          "headers": { "Authorization": "Bearer ref_..." }
        }
      }
    }
    ```

    Leave out `headers` to sign in with OAuth.
  </Accordion>

  <Accordion title="VS Code" id="vs-code">
    Run **MCP: Add Server**, choose **HTTP**, enter `https://mcp.rumoro.dev/mcp` and name it `rumoro`. With a key, use

    ```json title=".vscode/mcp.json"
    {
      "servers": {
        "rumoro": {
          "type": "http",
          "url": "https://mcp.rumoro.dev/mcp",
          "headers": { "Authorization": "Bearer ref_..." }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Codex CLI" id="codex-cli">
    ```bash
    codex mcp add rumoro --url https://mcp.rumoro.dev/mcp
    codex mcp login rumoro
    ```

    The [Codex page](https://rumoro.dev/codex) walks through it with example questions. With a key, read it from an environment variable.

    ```bash
    export RUMORO_API_KEY="ref_..."
    codex mcp add rumoro --url https://mcp.rumoro.dev/mcp --bearer-token-env-var RUMORO_API_KEY
    ```
  </Accordion>

  <Accordion title="Grok" id="grok">
    Open [grok.com/connectors](https://grok.com/connectors), choose **New Connector**, then **Custom**, and enter `https://mcp.rumoro.dev/mcp`. Grok runs the OAuth sign-in. On Business and Enterprise plans an admin provisions the connector first. The [Grok page](https://rumoro.dev/grok) walks through it with example questions.
  </Accordion>

  <Accordion title="Hermes Agent" id="hermes">
    Add the server under `mcp_servers`, then run `hermes mcp login rumoro`. Hermes registers itself with Rumoro, so there's no client ID to create.

    ```yaml title="~/.hermes/config.yaml"
    mcp_servers:
      rumoro:
        url: "https://mcp.rumoro.dev/mcp"
        auth: oauth
    ```

    Check it with `hermes mcp test rumoro`, or run `/reload-mcp` in a session. The [Hermes page](https://rumoro.dev/hermes) walks through it with example questions. With a key, replace `auth: oauth` with `headers: { Authorization: "Bearer ${RUMORO_API_KEY}" }` and put `RUMORO_API_KEY` in `~/.hermes/.env`.
  </Accordion>

  <Accordion title="OpenClaw" id="openclaw">
    ```bash
    openclaw mcp add rumoro --url https://mcp.rumoro.dev/mcp --transport streamable-http --auth oauth
    openclaw mcp login rumoro
    openclaw mcp doctor rumoro --probe
    ```

    The [OpenClaw page](https://rumoro.dev/openclaw) walks through it with example questions. To use an API key instead, install the [Rumoro skill](/integrations/openclaw).
  </Accordion>

  <Accordion title="Gemini CLI, Windsurf and other clients" id="other-clients">
    Use the Cursor settings with the client's own file and URL key.

    | Client | File | URL key |
    | --- | --- | --- |
    | Gemini CLI | `~/.gemini/settings.json` | `httpUrl` |
    | Windsurf | `~/.codeium/windsurf/mcp_config.json` | `serverUrl` |
    | Any other | The client's MCP settings | `url`, plus `"type": "http"` |
  </Accordion>
</Accordions>

## Help your agent find its way

Tell the agent what you track in `AGENTS.md`, `CLAUDE.md` or the client's rules file.

```markdown title="AGENTS.md"
## Rumoro

- Workspace: Driftwood (connected through the `rumoro` MCP server)
- Brand keyword `driftwood`, competitors `flagpole` and `switchboard`, topic `feature flags`
- "Relevant" means the classifier scored it 40 or more; matched counts include noise
- Start with `search_mentions` and a time range; use `get_analytics_*` for numbers over a period
- Only change keywords or alerts when asked; triage (status, assignee, notes) is fine
```

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `401` "Missing or invalid credentials" | Sign in again, or check the header and that the key isn't revoked |
| The client asks to authenticate | Run its sign-in, for Claude Code `/mcp` and **Authenticate** |
| No tools are listed | Reload the client |
| "Unknown tool" for a write tool | The key or sign-in only has `read` |
| A list seems cut short | `search_mentions` returns 10 at a time. Narrow the filters, or use the REST API to page through everything. |
| `405` | Use streamable HTTP (`POST /mcp`), not the older SSE transport |