MCP Server

Overview

The WaterrAI MCP server is a hosted Model Context Protocol 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 — direct server-to-server automation. Same wai_ key, raw HTTP.
Claude Code skill — for building on top of the API. The skill teaches the agent the resource model; MCP lets the agent call the API live.

Prerequisites

A WaterrAI account

A `wai_` API key

Create one from waterr.ai/settings → API Keys, or via the REST API — see Authentication. The MCP server authenticates with the same key you’d use against the REST API.

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.

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_...

Claude Desktop

Open Settings → Connectors

In Claude Desktop, open Settings (⌘,) and select the Connectors tab.

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.

Verify

Start a new chat and ask “What WaterrAI tools do you have?” — Claude should list the tools from the Tools section.

Claude Code

Add the MCP server

Run from any shell:

claude mcp add waterr \
  --transport http \
  --header "Authorization: Bearer wai_YOUR_KEY" \
  https://api.waterr.ai/v1/mcp

Verify

claude mcp list

waterr should appear with status connected.

ChatGPT

Open Settings → Connectors

Available on plans with MCP connector support. Open Settings → Connectors → Add.

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

Cursor

Add to ~/.cursor/mcp.json:

{
  "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.

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.waterr]
url = "https://api.waterr.ai/v1/mcp"
transport = "http"

[mcp_servers.waterr.headers]
Authorization = "Bearer wai_YOUR_KEY"

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.

Authentication

The MCP server uses wai_ API-key bearer auth — the same key format as the REST API. 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.

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.

To rotate or revoke a key, manage it from waterr.ai/settings → API Keys, or via the REST API.

Tools

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

Tool	Description	Example prompt
`list_scenarios`	List scenarios in your active workspace.	”Show me my interview scenarios.”
`get_scenario`	Fetch a single scenario by ID.	”Show me scenario `scn_abc123`.”
`list_meetings`	List meetings (filterable by status, scenario, date).	”What meetings did I run yesterday?”
`get_meeting`	Fetch a meeting’s status, participants, and URLs.	”What’s the status of meeting `mtg_abc123`?”
`get_analysis`	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 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.

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.

Troubleshooting

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 ...).

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 → API Keys instead.

401 Invalid API secret

The key was revoked or doesn’t exist. Generate a new one and update your client’s config.

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.

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).

FAQ

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.

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 directly is usually simpler than going through the MCP transport.

Which plan do I need?

Available on all plans. Per-tool plan gating may be added as the toolset grows.

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.

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.

Can I run my own MCP server against the REST API?

Yes — the REST API is the canonical surface and you’re welcome to wrap it in a custom MCP server. The hosted one is the supported turnkey path.

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.

Getting Started

Meetings

Personas

Scenarios

Embed Scenario

Post-Meeting Data

Goals

Avatars

Voices

Tools

Users

Guides

Integrations

Agent Skills

Overview

Prerequisites

How to connect

Authentication

Tools

Limits and permissions

Troubleshooting

FAQ

​Overview

​Prerequisites

​How to connect

​Authentication

​Tools

​Limits and permissions

​Troubleshooting

​FAQ

Overview

Prerequisites

How to connect

Authentication

Tools

Limits and permissions

Troubleshooting

FAQ