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.ai, 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, via OAuth sign-in or a wai_ API key.
REST API — direct server-to-server automation. 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.

How to connect

All clients connect to the same endpoint:

https://waterr.ai/backend/mcp

Two ways to authenticate — both are first-class:

OAuth sign-in (recommended for interactive clients). Add the URL with no credentials; your client discovers the WaterrAI authorization server, opens a browser consent screen, and manages short-lived tokens automatically. This is the only path claude.ai / Claude Desktop custom connectors support.
wai_ API key (for headless / CI / key-based clients). Send Authorization: Bearer wai_... on every request. Create a key at waterr.ai/settings → API Keys.

claude.ai / Claude Desktop (OAuth)

Open Settings → Connectors

In claude.ai or Claude Desktop, open Settings and select Connectors.

Add a custom connector

Click Add custom connector, name it WaterrAI, and paste:

https://waterr.ai/backend/mcp

No token needed — click Connect and approve access on the WaterrAI consent screen that opens.

Verify

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

Claude Code

OAuth (no key handling):

claude mcp add waterr --transport http https://waterr.ai/backend/mcp

Then run /mcp inside Claude Code and pick waterr → Authenticate to complete the browser sign-in.Or with an API key:

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

Verify with claude mcp list — waterr should show connected.

ChatGPT

Open Settings → Connectors

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

Add a custom MCP server

Name it WaterrAI and paste the URL. Use OAuth if your workspace supports it, or configure a custom Authorization header with your wai_ key:

URL:     https://waterr.ai/backend/mcp
Header:  Authorization: Bearer wai_YOUR_KEY

Cursor

Add to ~/.cursor/mcp.json (omit headers to use OAuth instead):

{
  "mcpServers": {
    "waterr": {
      "url": "https://waterr.ai/backend/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://waterr.ai/backend/mcp"
transport = "http"

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

Other MCP clients

Any client that speaks the MCP streamable-HTTP transport can connect:

URL: https://waterr.ai/backend/mcp
Transport: http (streamable, stateless)
Auth: OAuth 2.1 (discovered via WWW-Authenticate / protected-resource metadata), or Authorization: Bearer wai_...

Refer to your client’s MCP documentation for the exact config syntax.

Authentication

The MCP server accepts two credentials, interchangeably:

OAuth 2.1 (interactive clients)

Spec-compliant MCP authorization: RFC 9728 protected-resource metadata, dynamic client registration, authorization-code flow with PKCE, rotating refresh tokens. Your client handles all of it — you just approve the consent screen once. Discovery endpoints, for the curious:

https://waterr.ai/.well-known/oauth-protected-resource/backend/mcp
https://waterr.ai/.well-known/oauth-authorization-server

OAuth tokens are scoped to the MCP toolset: every read tool, plus create_meeting. They cannot write anything else through the REST API. They expire after an hour and refresh automatically; revoke a connection anytime from waterr.ai/settings → API Keys.

`wai_` API key (headless / CI)

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. Prefer OAuth for anything interactive; keys are for automation that can’t open a browser.

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?”
`create_meeting`	Create a shareable meeting link for one of your scenarios — the “Send Agent” flow.	”Send an agent to run my discovery call with Priya at Acme.”

create_meeting returns a short join URL like https://waterr.ai/qsk-abg-fin, exactly as Creator Studio does. Nothing is sent anywhere — the link goes live only when you share it, and a meeting appears in list_meetings once someone joins. The scenario must be one your workspace owns; use list_scenarios to find its ID. More tools (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 credential.
Workspace scope: the MCP follows the workspace of the key, or of the user who approved the OAuth consent.
Reads, plus one write: every tool is read-only except create_meeting, which only ever creates a new share link — it never edits or deletes a scenario, meeting, or existing link. OAuth tokens are hard-limited server-side to exactly this surface, so a leaked token can’t be used to write anything else.

Treat your MCP-connected agent like a logged-in user. Anything your credential can read via the REST API, the agent can read too via the MCP — and it can mint meeting links that anyone holding the URL can join.

Troubleshooting

401 Missing Authorization header

Your client isn’t sending credentials and didn’t run the OAuth flow. Either complete the OAuth sign-in your client offers, or configure Authorization: Bearer wai_... (not X-API-Key, not Token ...).

401 Invalid OAuth access token

The token expired (they last 1 hour) and your client failed to refresh, or the connection was revoked. Reconnect the connector — a fresh consent takes seconds.

401 Unsupported token type

The server accepts wai_ API keys or OAuth tokens it issued. If you’re pasting a Google/Microsoft access token, create a proper wai_ API key from waterr.ai/settings → API Keys instead — or just use the OAuth flow.

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 credential. Back off and retry. If an agent regularly hits the cap, prefer batched tools (list_meetings over N × get_meeting).

FAQ

Should I use OAuth or an API key?

OAuth for anything interactive (claude.ai, Claude Desktop, Cursor on your laptop) — tokens are short-lived, limited to the MCP tool surface, and revocable per connection. API keys for headless automation (CI jobs, servers) where no browser is available.

Does the MCP server use my REST API key?

It can — the same wai_ key works on both surfaces, and revoking it disconnects both. OAuth connections are separate credentials; revoking a key doesn’t affect them.

Can I use the MCP server from a CI job or backend?

Yes — use a wai_ key (no interactive sign-in needed). 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) — turn off create_meeting there if you want a purely read-only connection. OAuth connections are additionally capped at the MCP tool surface server-side, regardless of client config.

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.

Getting Started

Meetings

Personas

Scenarios

Embed Scenario

Post-Meeting Data

Goals

Avatars

Voices

Tools

Users

Guides

Integrations

Agent Skills

Overview

How to connect

Authentication

OAuth 2.1 (interactive clients)

`wai_` API key (headless / CI)

Tools

Limits and permissions

Troubleshooting

FAQ

​Overview

​How to connect

​Authentication

​OAuth 2.1 (interactive clients)

​wai_ API key (headless / CI)

​Tools

​Limits and permissions

​Troubleshooting

​FAQ

Overview

How to connect

Authentication

OAuth 2.1 (interactive clients)

`wai_` API key (headless / CI)

Tools

Limits and permissions

Troubleshooting

FAQ