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

# MCP Server

> Connect WaterrAI to Claude, ChatGPT, Cursor and other MCP-aware clients so your agent can list scenarios, fetch meetings, and pull analyses on your behalf.

## Overview

The WaterrAI MCP server is a hosted [Model Context Protocol](https://modelcontextprotocol.io) endpoint that exposes the Core APIs as agent-callable tools. Once you connect it to an MCP-aware client (Claude Desktop, Claude Code, ChatGPT, Cursor, Codex), your agent can do things like:

* *"List my interview scenarios and tell me which ones I used this week."*
* *"Pull yesterday's onboarding meeting and show me the analysis."*
* *"What was the score on meeting `abc123`?"*

When to use the MCP server vs. the alternatives:

* **MCP** — interactive use from an agent client, on your own account, using your `wai_` API key.
* **[REST API](/api-reference/quickstart)** — direct server-to-server automation. Same `wai_` key, raw HTTP.
* **[Claude Code skill](/skills/claude-code)** — for *building* on top of the API. The skill teaches the agent the resource model; MCP lets the agent *call* the API live.

## Prerequisites

<Steps>
  <Step title="A WaterrAI account">
    Sign in at [waterr.ai](https://waterr.ai) with Google, Microsoft, or LinkedIn.
  </Step>

  <Step title="A `wai_` API key">
    Create one from [waterr.ai/settings](https://waterr.ai/settings) → **API Keys**, or via the REST API — see [Authentication](/api-reference/authentication). The MCP server authenticates with the same key you'd use against the REST API.
  </Step>

  <Step title="An MCP-compatible client">
    Claude Desktop, Claude Code, ChatGPT (Desktop, MCP-enabled workspace), Cursor, Codex CLI, or any client that speaks the MCP HTTP transport.
  </Step>
</Steps>

## How to connect

All clients connect to the same endpoint, using HTTP Bearer auth with your `wai_` key:

```
https://api.waterr.ai/v1/mcp
```

```
Authorization: Bearer wai_...
```

<AccordionGroup>
  <Accordion title="Claude Desktop">
    <Steps>
      <Step title="Open Settings → Connectors">
        In Claude Desktop, open **Settings** (⌘,) and select the **Connectors** tab.
      </Step>

      <Step title="Add a custom connector">
        Click **Add custom connector**, name it `WaterrAI`, and paste:

        ```
        https://api.waterr.ai/v1/mcp
        ```

        Under **Authentication**, choose **Bearer token** and paste your `wai_` key.
      </Step>

      <Step title="Verify">
        Start a new chat and ask *"What WaterrAI tools do you have?"* — Claude should list the tools from the [Tools](#tools) section.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Claude Code">
    <Steps>
      <Step title="Add the MCP server">
        Run from any shell:

        ```bash theme={null}
        claude mcp add waterr \
          --transport http \
          --header "Authorization: Bearer wai_YOUR_KEY" \
          https://api.waterr.ai/v1/mcp
        ```
      </Step>

      <Step title="Verify">
        ```bash theme={null}
        claude mcp list
        ```

        `waterr` should appear with status `connected`.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="ChatGPT">
    <Steps>
      <Step title="Open Settings → Connectors">
        Available on plans with MCP connector support. Open **Settings → Connectors → Add**.
      </Step>

      <Step title="Add a custom MCP server">
        Name it `WaterrAI`, paste the URL, and configure a custom `Authorization` header with your `wai_` key:

        ```
        URL:     https://api.waterr.ai/v1/mcp
        Header:  Authorization: Bearer wai_YOUR_KEY
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Cursor">
    Add to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "waterr": {
          "url": "https://api.waterr.ai/v1/mcp",
          "headers": {
            "Authorization": "Bearer wai_YOUR_KEY"
          }
        }
      }
    }
    ```

    Restart Cursor. The `waterr` tools should appear in the agent's tool list.
  </Accordion>

  <Accordion title="Codex CLI">
    Add to `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.waterr]
    url = "https://api.waterr.ai/v1/mcp"
    transport = "http"

    [mcp_servers.waterr.headers]
    Authorization = "Bearer wai_YOUR_KEY"
    ```
  </Accordion>

  <Accordion title="Other MCP clients">
    Any client that supports the MCP HTTP transport with custom headers can connect using:

    * **URL:** `https://api.waterr.ai/v1/mcp`
    * **Transport:** `http` (streamable, stateless)
    * **Auth:** `Authorization: Bearer wai_...`

    Refer to your client's MCP documentation for the exact config syntax.
  </Accordion>
</AccordionGroup>

## Authentication

The MCP server uses **`wai_` API-key bearer auth** — the same key format as the [REST API](/api-reference/authentication). Send it on every request:

```
Authorization: Bearer wai_...
```

The key inherits the permissions and workspace of whoever created it. Treat it as a credential — anyone with the key can call the same tools as the owning user.

<Note>
  **OAuth is coming.** A browser-based OAuth flow (so end users can connect without copy-pasting a key) is on the roadmap. Until it ships, every MCP connection uses a `wai_` key.
</Note>

To rotate or revoke a key, manage it from [waterr.ai/settings](https://waterr.ai/settings) → **API Keys**, or via the [REST API](/api-reference/authentication#revoking-a-key).

## Tools

Each tool maps to a REST endpoint — click through for the full request/response schema.

| Tool                                                                     | Description                                            | Example prompt                                            |
| ------------------------------------------------------------------------ | ------------------------------------------------------ | --------------------------------------------------------- |
| [`list_scenarios`](/api-reference/endpoint/get-scenarios)                | List scenarios in your active workspace.               | *"Show me my interview scenarios."*                       |
| [`get_scenario`](/api-reference/endpoint/get-scenarios-id)               | Fetch a single scenario by ID.                         | *"Show me scenario `scn_abc123`."*                        |
| [`list_meetings`](/api-reference/endpoint/get-meetings)                  | List meetings (filterable by status, scenario, date).  | *"What meetings did I run yesterday?"*                    |
| [`get_meeting`](/api-reference/endpoint/get-meetings-id)                 | Fetch a meeting's status, participants, and URLs.      | *"What's the status of meeting `mtg_abc123`?"*            |
| [`get_analysis`](/api-reference/endpoint/get-analyses-meeting-meetingid) | Return scored goals + summary for a completed meeting. | *"How did the candidate score in yesterday's interview?"* |

More tools (creating meetings, managing personas and voices, fetching transcripts) are on the roadmap. For anything not in this list today, fall back to the [REST API](/api-reference/quickstart) directly.

## Limits and permissions

* **Rate limit:** `100 requests / minute` per `wai_` key.
* **Workspace scope:** the MCP follows the workspace the key was created in.
* **Read-only today:** the shipped toolset is read-only. Destructive tools (when added) will be opt-in per client.

<Warning>
  Treat your MCP-connected agent like a logged-in user. Anything the `wai_` key can do via the REST API, the agent can do too via the MCP — including, once write tools ship, creating meetings or modifying scenarios.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Missing Authorization header">
    Your client isn't sending the bearer header. Re-check the connector config and confirm `Authorization: Bearer wai_...` is set (not `X-API-Key`, not `Token ...`).
  </Accordion>

  <Accordion title="401 Unsupported token type">
    The server only accepts `wai_`-prefixed API keys. If you're trying to paste a Google/Microsoft access token, create a proper `wai_` API key from [waterr.ai/settings](https://waterr.ai/settings) → **API Keys** instead.
  </Accordion>

  <Accordion title="401 Invalid API secret">
    The key was revoked or doesn't exist. Generate a new one and update your client's config.
  </Accordion>

  <Accordion title="Tools aren't showing up in my client">
    Most clients only refresh their tool list on startup. Quit and reopen the client after adding the connector. In Claude Code, run `claude mcp list` to confirm `waterr` is `connected`.
  </Accordion>

  <Accordion title="Rate-limit errors (429)">
    You're over `100 requests / minute` on that key. Back off and retry. If an agent regularly hits the cap, prefer batched tools (`list_meetings` over N × `get_meeting`).
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Does the MCP server use my REST API key?">
    Yes — the same `wai_` key. The MCP server is a thin protocol wrapper around the REST API; revoking the key disconnects both.
  </Accordion>

  <Accordion title="Can I use the MCP server from a CI job or backend?">
    You can — there's no interactive sign-in. That said, if you're writing your own server code, calling the [REST API](/api-reference/quickstart) directly is usually simpler than going through the MCP transport.
  </Accordion>

  <Accordion title="Which plan do I need?">
    Available on all plans. Per-tool plan gating may be added as the toolset grows.
  </Accordion>

  <Accordion title="Does my meeting data leave WaterrAI?">
    The MCP server runs on WaterrAI infrastructure. Only the explicit tool responses your agent requests are returned to the client — transcripts, recordings, and analyses are not pre-shared.
  </Accordion>

  <Accordion title="Can I limit what tools an agent can call?">
    Most clients support per-tool allowlists (Claude Desktop's connector settings, Cursor's MCP config). Use this to scope an agent to read-only operations.
  </Accordion>

  <Accordion title="Can I run my own MCP server against the REST API?">
    Yes — the [REST API](/api-reference/quickstart) is the canonical surface and you're welcome to wrap it in a custom MCP server. The hosted one is the supported turnkey path.
  </Accordion>

  <Accordion title="When will OAuth land?">
    OAuth (so end users can connect without pasting an API key) is on the roadmap but not dated. Until it ships, MCP requires a `wai_` key.
  </Accordion>
</AccordionGroup>