clintplay-mcp

Clintplay MCP server for Claude Code and other MCP clients. Gives AI agents read/write access to Clintplay session recordings, errors, analytics, and more.

Install

# One-shot via npx (no install needed)
# Pin to @latest so npx never serves a stale cached version after we ship updates.
npx -y clintplay-mcp@latest

# Or install globally
npm install -g clintplay-mcp@latest

Configuration

Claude Code MCP config (~/.claude/claude_desktop_config.json)

{
  "mcpServers": {
    "clintplay": {
      "command": "npx",
      "args": ["-y", "clintplay-mcp@latest"],
      "env": {
        "CLINTPLAY_PAT": "cp_pat_...",
        "CLINTPLAY_API_URL": "https://api.clintplay.example"
      }
    }
  }
}

Generate a PAT at Clintplay dashboard → Settings → Personal Access Tokens.

REST contract

The tools are a 1:1 mapping onto REST endpoints under /v1/mcp/*. If you are integrating server-to-server, call those directly — the MCP protocol adds a handshake and an envelope without adding capability.

The contract is generated from this tool registry joined to the live route table, so it cannot drift from what the tools request:

GET https://<your-api>/v1/mcp/openapi.json     (no auth required)
docs/openapi-mcp.json                          (committed, drift-tested)

Environment variables

| Variable | Required | Default | Description | |---|---|---|---| | CLINTPLAY_PAT | Yes | — | Personal access token (cp_pat_* format). Generate one in Settings. | | CLINTPLAY_API_URL | Yes | — | API origin (e.g. https://clintplay.your-domain.com). A path is accepted but ignored with a warning on stderr — tool paths are absolute, so anything after the host is dropped. A trailing /v1 is harmless (identical result); any other prefix means this client cannot reach your API. |

Local development

Point the server at a locally-running API:

CLINTPLAY_API_URL=http://localhost:3001 CLINTPLAY_PAT=cp_pat_... npx clintplay-mcp@latest

Available tools

52 tools across seven categories:

• Discovery — list projects, list sessions, get session details
• Business events — list event definitions, event series, property definitions, property breakdown, retention cohorts, distinct users per window, owner activity
• Granular reads — session events, errors, analytics, jobs
• Cross-session analysis — aggregate queries, trend detection
• Annotations / share / links — create annotations, share sessions, manage links
• Execution — extract repro steps, replay, run sandbox queries
• Meta — whoami (GET /v1/mcp/whoami)

Plus 7 URI-addressable resources and 6 prompt runbooks.

Transports

stdio (default, for Claude Code / Cursor / Claude Desktop): run npx clintplay-mcp with CLINTPLAY_PAT and CLINTPLAY_API_URL set.

HTTP (for service-to-service callers): the Clintplay API serves MCP over Streamable HTTP at POST /v1/mcp-rpc. Authenticate with Authorization: Bearer cp_pat_… and send Content-Type: application/json. Scopes and project membership are enforced exactly as on stdio. Four tools are withheld on this transport because they enqueue Playwright/sandbox work: extract_repro, replay_session, run_query_on_session, get_screenshot.

License

MIT — see LICENSE.