@wave-av/mcp-server

MCP (Model Context Protocol) server that exposes WAVE streaming APIs as tools for AI coding assistants (Claude Code, Cursor, Windsurf).

Live → · docs · npm · repo · Docs · Status

This README is machine-generated from WAVE's grounded Single Source of Truth — every factual claim below traces to a resolver that npm run verify checks against the live repo and live endpoints. Nothing here is asserted without a receipt.

Quick start

npx @wave-av/mcp-server

{
  "mcpServers": {
    "wave": {
      "command": "npx",
      "args": ["-y", "@wave-av/mcp-server"],
      "env": {
        "WAVE_API_KEY": "wave_live_..."
      }
    }
  }
}

Setup

1. Get an API key

# Via CLI
wave auth login

# Or create at https://wave.online/settings/api-keys

2. Configure your AI tool

Add to your .mcp.json (Claude Code, Cursor, Windsurf, etc.) — see the Quick start config above.

Available tools — Streams

| Tool | Description | | --- | --- | | wave_list_streams | List all streams with pagination and status filtering | | wave_create_stream | Create a new stream with protocol and privacy options | | wave_start_stream | Start streaming on an existing stream | | wave_stop_stream | Stop an active stream | | wave_get_stream_health | Get real-time health metrics for a stream |

Available tools — Studio

| Tool | Description | | --- | --- | | wave_list_productions | List studio production sessions | | wave_create_production | Create a new multi-camera production |

Available tools — Analytics

| Tool | Description | | --- | --- | | wave_get_viewers | Get current viewer count and breakdown | | wave_get_stream_metrics | Get detailed stream performance metrics |

Available tools — Billing

| Tool | Description | | --- | --- | | wave_get_subscription | Get current subscription plan and status | | wave_get_usage | Get current period usage and limits |

Resources

Access WAVE entities directly via the wave:// URI scheme:

• wave://streams/{id} - Stream configuration and status
• wave://productions/{id} - Studio production details

Environment variables

| Variable | Required | Default | Description | | --- | --- | --- | --- | | WAVE_API_KEY | Yes | - | Your WAVE API key | | WAVE_BASE_URL | No | https://wave.online | API base URL |

In-process (Claude Agent SDK) mode

For consumers already running inside a Claude Agent SDK session, the same tools are available in-process — skipping the stdio subprocess hop (~50 ms vs ~500 ms cold start). The tool list is shared with the stdio server (src/tools/index.ts), so the two transports never drift.

@anthropic-ai/claude-agent-sdk is an optional peer dependency: stdio users never need it. Install it only for this mode:

npm install @wave-av/mcp-server @anthropic-ai/claude-agent-sdk

import { query } from "@anthropic-ai/claude-agent-sdk";
import { createWaveSdkMcpServer } from "@wave-av/mcp-server/sdk-server";

const wave = await createWaveSdkMcpServer();
for await (const message of query({
  prompt: "List my active streams",
  options: { mcpServers: { wave }, env: { WAVE_API_KEY: process.env.WAVE_API_KEY } },
})) {
  // handle messages
}

Setup for other AI tools

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "wave": {
      "command": "npx",
      "args": ["-y", "@wave-av/mcp-server"],
      "env": { "WAVE_API_KEY": "wave_live_..." }
    }
  }
}

Windsurf

Add to Windsurf MCP settings with the same configuration.

Troubleshooting

Server not starting

Verify your API key is set:

echo $WAVE_API_KEY

Tools not appearing

Restart your AI tool after adding the MCP configuration. Most tools require a restart to detect new MCP servers.

Connection errors

The MCP server uses stdio transport (no network listener). If you see connection errors, check that npx can run successfully:

npx @wave-av/mcp-server --version

Testing the server

Send a JSON-RPC initialize request to verify:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | npx @wave-av/mcp-server

Related packages

• @wave-av/sdk — TypeScript SDK (34 API modules)
• @wave-av/adk — Agent Developer Kit
• @wave-av/cli — Command-line interface
• @wave-av/create-app — Scaffold a new project
• OpenAPI spec — Full API specification

Development

cd packages/mcp-server
pnpm install
pnpm run build
pnpm run dev       # Watch mode
pnpm run type-check

License

MIT

Capabilities

| Capability | Status | | --- | --- | | Control a PTZ camera (pan, tilt, zoom, focus, preset recall/store). | | | Create a clip from a recorded stream, optionally exporting to social platforms. | | | Create a new multi-camera studio production. | | | Create a new stream (protocol, recording, region options). | | | Get real-time stream health metrics (bitrate, frame rate, latency). | | | Get detailed stream performance metrics (bitrate, latency, quality, error rates). | | | Get current subscription plan, billing cycle, and feature entitlements. | | | Get current billing-period usage (streaming minutes, storage, bandwidth). | | | Get current viewer count and viewer demographics for a stream or account-wide. | | | List all studio productions in the WAVE account. | | | List all streams in the WAVE account with pagination and status filtering. | | | Mark a moment in a stream as a highlight for later clipping. | | | Moderate a chat message in a live stream (block, flag, or allow). | | | Show, hide, or update an HTML5 graphics overlay on a production. | | | Start real-time captions/transcription on a stream. | | | Start a stream by ID, transitioning it to the active state. | | | Stop an active stream by ID. | | | Switch the live program output to a different camera/source in a Cloud Switcher session. | |

For AI agents

Exposes the MCP tool wave-mcp-server over stdio.

The receipts

Every claim below is checked by npm run verify against the live repo or endpoint — a non-pass verdict fails the gate.

| Claim | How it's verified | | --- | --- | | Documentation surface is docs.wave.online/mcp | resolved by grepping package.json | | Published npm package name is @wave-av/mcp-server | resolved by grepping package.json | | wave_control_camera tool defined in src/tools/production.ts | resolved by grepping src/tools/production.ts | | Exposes 18 MCP tools | resolved by grepping capabilities.json | | wave_create_clip tool defined in src/tools/production.ts | resolved by grepping src/tools/production.ts | | wave_create_production tool defined in src/tools/studio.ts | resolved by grepping src/tools/studio.ts | | wave_create_stream tool defined in src/tools/streams.ts | resolved by grepping src/tools/streams.ts | | wave_get_viewers tool defined in src/tools/analytics.ts | resolved by grepping src/tools/analytics.ts | | wave_list_productions tool defined in src/tools/studio.ts | resolved by grepping src/tools/studio.ts | | wave_list_streams tool defined in src/tools/streams.ts | resolved by grepping src/tools/streams.ts | | wave_mark_highlight tool defined in src/tools/production.ts | resolved by grepping src/tools/production.ts | | wave_moderate_chat tool defined in src/tools/production.ts | resolved by grepping src/tools/production.ts | | wave_show_graphic tool defined in src/tools/production.ts | resolved by grepping src/tools/production.ts | | wave_start_captions tool defined in src/tools/production.ts | resolved by grepping src/tools/production.ts | | wave_start_stream tool defined in src/tools/streams.ts | resolved by grepping src/tools/streams.ts | | wave_stop_stream tool defined in src/tools/streams.ts | resolved by grepping src/tools/streams.ts | | wave_get_stream_health tool defined in src/tools/streams.ts | resolved by grepping src/tools/streams.ts | | wave_get_stream_metrics tool defined in src/tools/analytics.ts | resolved by grepping src/tools/analytics.ts | | wave_get_subscription tool defined in src/tools/billing.ts | resolved by grepping src/tools/billing.ts | | wave_switch_camera tool defined in src/tools/production.ts | resolved by grepping src/tools/production.ts | | wave_get_usage tool defined in src/tools/billing.ts | resolved by grepping src/tools/billing.ts | | Server connects via stdio transport (no network listener) | resolved by grepping src/server.ts |

Topics

wave · mcp · model-context-protocol · ai · streaming · tools

Built by WAVE Online, LLC · wave.online · Docs · LinkedIn