This guide walks you through pointing Claude Code, Claude Desktop, Cursor, or any MCP-compatible AI assistant at your Captainbook Statistics MCP server. After setup, you can ask the assistant questions like "How was revenue last weekend?" or "Which products had the highest occupancy this month?" and get answers grounded in your real booking data.
Prerequisites
A Captainbook account on Starter, Extended, Ultra, or Corporate plan (Free and Legacy plans don't include MCP).
The user creating the token must have the View Reports permission.
An MCP-compatible client installed: Claude Code, Claude Desktop, Cursor, or anything else that speaks the Model Context Protocol.
Step 1 — Generate a connection in Captainbook
Open Captainbook and click your avatar (top-left).
From the dropdown, click MCP Connections.
Pick Statistics from the Integration dropdown.
Read the preview card to see example questions you can ask.
Give the connection a name that helps you remember which device or assistant uses it (e.g., "laptop — analytics").
Pick the business unit you want this connection to read data from. Each token is pinned to one business unit; create a separate token if you need a different one.
Click Generate.
A modal opens with two pieces of information:
Token — a long string starting with a number, then
|, then a random tail (e.g.,7|yg09kP...). You'll only see this once.Configuration — a snippet, with a client picker (Claude Code, Claude Desktop, Cursor, ChatGPT) at the top that reshapes the snippet for whichever assistant you're using. Pick yours, copy, and follow the matching option below.
Step 2 — Add the connection to your AI assistant
Option A — Claude Code (native HTTP)
Claude Code speaks HTTP MCP natively, so you can paste the snippet as-is.
Project-scoped (recommended for shared codebases): paste it into
.mcp.jsonat the repo root, alongside any existing servers.User-scoped (available everywhere): add it to
~/.claude.jsonundermcpServers, or run:claude mcp add --transport http captainbook-statistics \ https://your-tenant.captainbook.io/mcp/statistics \ --header "Authorization: Bearer <your-token>"
Restart Claude Code (or reload the project) and the tools appear in the next session.
Option B — Claude Desktop (via mcp-remote)
Claude Desktop doesn't yet support HTTP MCP servers directly, so wrap the connection with mcp-remote, which bridges stdio (what Desktop speaks) to HTTP (what Captainbook speaks). You'll need Node.js installed — npx ships with it.
Open Claude Desktop → Settings → Developer → Edit Config. This opens
claude_desktop_config.json.Paste this block inside
mcpServers(replace URL and token with the values from your modal):{ "mcpServers": { "captainbook-statistics": { "command": "npx", "args": [ "-y", "mcp-remote", "https://your-tenant.captainbook.io/mcp/statistics", "--transport", "http-only", "--header", "Authorization: Bearer <your-token>" ] } } }The
--transport http-onlyflag is required — without it,mcp-remotetries SSE first and fails against Captainbook's POST-only endpoint with a 405.Save and fully quit Claude Desktop (⌘Q on macOS — closing the window is not enough), then re-open it.
Option C — Cursor
Cursor speaks HTTP MCP natively. Pick Cursor in the modal — the snippet shape matches Claude Code — and paste it into ~/.cursor/mcp.json (user-level) or .cursor/mcp.json at the project root. Restart Cursor.
Option D — ChatGPT (custom Connector)
ChatGPT supports remote MCP servers via custom Connectors on Business, Enterprise, Edu, and Pro plans, and via Developer Mode for Plus users. Free ChatGPT can't add custom MCP servers.
The modal's ChatGPT tab shows a Server URL and an Authorization header value instead of a snippet — ChatGPT's Connector form is a UI, not a paste-target.
In ChatGPT, go to Settings → Connectors → Add custom connector (or, on Plus, enable Developer Mode in Settings → Apps & Connectors first).
MCP Server URL — paste the URL from the modal (e.g.
https://your-tenant.captainbook.io/mcp/statistics).Authentication — choose Custom and add an
Authorizationheader with the valueBearer <your-token>(the modal shows it preformatted). If your ChatGPT version offers a separate "Bearer token" field, paste only the token without theBearerprefix.Save the connector. ChatGPT will probe the server and list the tools.
Caveats specific to ChatGPT:
Tool calls default to per-call approval — ChatGPT will ask before each call. Switch to per-session approval if that's too noisy.
ChatGPT's Deep Research agent only invokes tools named
searchandfetch; the Captainbook Statistics tools are usable in normal chat / Developer Mode but won't surface in Deep Research today.
Other clients
Check whether your client speaks HTTP natively (use the Claude Code / Cursor snippet) or stdio-only (use the Claude Desktop wrapper). Both shapes are produced by the modal — just pick the matching tab.
Your client will now show captainbook-statistics in its list of available tools when you start a new chat.
Step 3 — Ask your first question
Try one of these:
"How was revenue last month compared to the same month last year?"
"Which products had the highest occupancy last weekend?"
"Which weekday is our busiest by booking count?"
Claude will pick the right metric and date range automatically. The data Claude sees is scoped to the business unit you picked at Step 1 — no other BUs are accessible through this token.
Managing your connections
List active connections — back at MCP Connections, you'll see every token you've issued, when it was last used, and which integration + tier it's for.
Revoke a connection — click Revoke next to any row. The next call from Claude using that token returns 401 Unauthenticated; revocation is immediate.
Plan downgrades — if your subscription drops below Starter, your Statistics tokens are auto-revoked and you'll receive an email explaining why.
Troubleshooting
Claude says "tool not found" — Quit and re-open the client (full quit on Desktop). Tool discovery happens at startup.
Claude Desktop fails with a 405 / "Method Not Allowed" — You're missing
--transport http-onlyin themcp-remoteargs. Without it,mcp-remotetries SSE first and Captainbook's POST-only endpoint rejects the GET.Claude Desktop says "spawn npx ENOENT" — Node.js isn't installed or not on Desktop's PATH. Install Node.js and restart Desktop.
ChatGPT says "Add custom connector" is missing — Your plan doesn't include connectors. Upgrade to Plus (Developer Mode), Pro, Business, Enterprise, or Edu.
ChatGPT says "connector validation failed" — The token was revoked, or the URL/Authorization header was pasted with extra whitespace. Re-issue and re-paste exactly as the modal shows.
Claude says "subscription required" — Your tenant's plan no longer includes the Statistics MCP. Upgrade or revoke and re-issue on a covered plan.
Claude says "rate limit reached" — You're hitting our per-token throttle (20 requests / 5 seconds, or 60 / minute). Wait and retry.
Claude returns weird data — The token is pinned to one BU. If you expected another BU's data, revoke and re-issue with the correct BU selected.
What this connection can do
Query 11 statistics metrics: summary, revenue, bookings, occupancy, products, channels, gift certificates, discounts, customers, resources, extras
Filter by date range (max 1 year), product, channel, location, day of week, time of day
Compare a primary period to a comparison period (year-over-year, etc.)
Sort and limit ranked metrics
What this connection cannot do
Modify any data (Statistics is read-only)
Access data from a different business unit than the one the token is pinned to
Bypass your plan's subscription tier
Survive plan downgrades (auto-revoked)
For inventory editing capabilities (update pricing, manage availability, refund bookings), see the Inventory MCP setup guide.