Skip to main content

Connect Claude Desktop to Captainbook (Inventory)

This guide walks you through connecting Claude Desktop (or Cursor, or any MCP-compatible AI assistant) to your Captainbook Inventory MCP server

Written by Jerome Bajou

This guide walks you through connecting Claude Code, Claude Desktop, Cursor, or any MCP-compatible AI assistant to your Captainbook Inventory MCP server. With this setup, you can ask the assistant to update product information, manage availability, and (with the right permissions) handle customer service operations like cancellations and refunds.

⚠️ Read this carefully. Inventory connections can change real business data. Choose your tier with intention. See What this connection can do below.

Prerequisites

  • A Captainbook account on Extended, Ultra, or Corporate plan (Inventory MCP is not included on Free, Legacy, or Starter plans).

  • For read-only tokens: the View Reports permission.

  • For edit tokens: the Issue Inventory MCP token (write tier) permission, typically granted to admins.

  • For customer service tokens: the Issue Inventory MCP token (customer service tier) permission, typically granted to admins only.

  • An MCP-compatible client installed: Claude Code, Claude Desktop, Cursor, or anything else that speaks the Model Context Protocol.

Choose a tier

Inventory MCP has three capability tiers. Pick the lowest one that covers your use case:

Tier

What the LLM can do

When to use

Read

Browse products, pricing, availability, bookings, customers. No mutations.

Asking questions about your inventory; reporting; analysis.

Edit

Read + update pricing, availability, product copy, configuration. Mutations commit on the LLM's call.

Letting Claude update product descriptions, set seasonal pricing, block availability for renovations.

Customer Service

Read + edit + cancel bookings, issue refunds, void gift certificates, resend confirmations.

Customer service teams using Claude to handle support tickets.

Higher tiers give the LLM more authority. Mistakes by the LLM are real changes to your data. The Edit tier can change pricing on a tour; the Customer Service tier can refund a customer.

Step 1 — Generate a connection in Captainbook

  1. Open Captainbook and click your avatar (top-left).

  2. From the dropdown, click MCP Connections.

  3. Pick Inventory, Inventory · Edit, or Inventory · Customer Service from the Integration dropdown — choose the lowest tier that covers your need.

  4. Read the preview card. For Edit and Customer Service tiers, a capability warning explains what mutations the LLM can perform. Take a moment to read it.

  5. Give the connection a name (e.g., "Sarah's laptop — refunds").

  6. Pick the business unit. Each token is pinned to one BU.

  7. Click Generate.

You'll see a modal with the Token and a Configuration block. The modal has a client picker — Claude Code, Claude Desktop, Cursor, ChatGPT — that reshapes the snippet for whichever assistant you're connecting from. 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.json at the repo root, alongside any existing servers.

  • User-scoped (available everywhere): add it to ~/.claude.json under mcpServers, or run:

    claude mcp add --transport http captainbook-inventory_write \   https://your-tenant.captainbook.io/mcp/inventory \   --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.

  1. Open Claude Desktop → Settings → Developer → Edit Config. This opens claude_desktop_config.json.

  2. Paste this block inside mcpServers (replace URL and token with the values from your modal):

    {   "mcpServers": {     "captainbook-inventory_write": {       "command": "npx",       "args": [         "-y",         "mcp-remote",         "https://your-tenant.captainbook.io/mcp/inventory",         "--transport",         "http-only",         "--header",         "Authorization: Bearer <your-token>"       ]     }   } }

    The --transport http-only flag is required — without it, mcp-remote tries SSE first and fails against Captainbook's POST-only endpoint with a 405.

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

  1. In ChatGPT, go to Settings → Connectors → Add custom connector (or, on Plus, enable Developer Mode in Settings → Apps & Connectors first).

  2. MCP Server URL — paste the URL from the modal (e.g. https://your-tenant.captainbook.io/mcp/inventory).

  3. Authentication — choose Custom and add an Authorization header with the value Bearer <your-token> (the modal shows it preformatted). If your ChatGPT version offers a separate "Bearer token" field, paste only the token without the Bearer prefix.

  4. 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 in the connector settings if that's too noisy (and you trust the tier).

  • ChatGPT's Deep Research agent only invokes tools named search and fetch; the Captainbook MCP 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.

Step 3 — Use the connection responsibly

Best practices for Edit tier

  • Use the dry-run flag. When asking Claude to make a change, you can ask "do a dry run first" — it returns a preview of what would change without committing. Only after reviewing should you ask Claude to commit.

  • Be specific. "Lower the price on tour X" is ambiguous. "Lower the adult price on tour X by 10% for August" is unambiguous.

  • Watch for accidents. The LLM will commit changes the moment you confirm. If you change your mind mid-sentence, say so before Claude executes.

Best practices for Customer Service tier

  • Verify the customer first. Claude can refund any booking the token has access to. Verify identity through your normal channels before authorizing a refund.

  • Ask for the dry run. Same advice — preview before commit.

  • Audit log review. Operations made through this token are recorded in the central audit log with timestamp, args, and outcome. If something goes wrong, the audit log is your reconstruction tool.

Try asking

Read tier

  • "Show me all products in the 'Wine Tour' category."

  • "What was booked for tomorrow?"

  • "How many active gift certificates does customer X have?"

Edit tier

  • "Lower the adult price on tour X by 10% for August. Show me a dry run first."

  • "Block availability for resource Y next Monday — there's a private event."

  • "Update the description of product Z to mention the new dietary options."

Customer Service tier

  • "Refund booking #4291 for the full amount — customer reports they never received their tickets. Dry run first, then commit."

  • "Cancel and notify the customer of booking #4128. The customer requested cancellation by email at 14:32 today."

  • "Void the gift certificate the customer just disputed. Dry run first."

Idempotency, dry-run, and retry behavior

  • Dry-run — Pass dry_run: true to any write operation. The CLI returns a preview without committing. This is the safest way to use the Edit and Customer Service tiers.

  • Idempotency-Key — When you make a change, Claude (well-behaved clients) sends an idempotency key. If the network drops mid-call and Claude retries, the same key is reused — the server replays the prior result instead of double-committing. This means a network blip won't refund a customer twice.

  • Retry semantics — If Claude says "the request failed, retry?" you can safely retry. Idempotency makes it a no-op if the original succeeded.

Plan downgrades

If your subscription drops below Extended, your Inventory tokens are auto-revoked. You'll receive an email naming the affected tokens and a link to re-create them once you're on a covered plan. The auto-revocation is immediate; the LLM's next call to a revoked token returns 401 Unauthenticated.

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-only in the mcp-remote args. Without it, mcp-remote tries 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 "permission denied" — The user who issued the token no longer has the underlying permission. Issue a fresh token from a user that does, or restore the permission.

  • Claude says "subscription required" — Your plan no longer covers Inventory MCP. Upgrade.

  • Claude returns "conflict" — Idempotency-Key replay with a different request body. Either use a fresh key or replay with the original body.

  • Claude says "this resource is locked" — Another operator is editing the same resource. Retry shortly.

  • Bulk availability — Claude says "accepted, verify later" — Bulk updates are async. Ask Claude to read the affected dates with the read tool to verify they applied.

What this connection can do

The Inventory CLI exposes ~91 endpoints. The MCP layer surfaces them as 9 tools (1 read tool + 8 domain-grouped write tools):

  • Read: list/show products, options, availability, pricing, discounts, gift certs, customers, bookings, transactions, guests, extras, questions, categories, resources, locations, media

  • Catalog edit: products, options, categories, extras, questions

  • Pricing edit: pricing categories, pricing tiers, discounts

  • Availability edit: availabilities, availability rules, resources

  • Locations edit: locations

  • Media edit: upload by public URL (with SSRF protection); delete

  • Customers edit: limited — guest profiles only

  • Gift certificates: read for all tiers; void = customer service tier only

  • Customer service: cancel bookings, comp, refund, resend confirmation, void gift cert

What this connection cannot do

  • Operate across business units (each token is pinned to one BU)

  • Bypass your plan's subscription tier

  • Operate beyond its tier (read tokens can't write; write tokens can't refund)

  • Survive plan downgrades (auto-revoked)

  • Upload media from local files (URL-only — public URLs only, private IPs blocked)

For statistics queries (revenue reports, occupancy aggregates), see the Statistics MCP setup guide.

Related Articles
Connect Claude Desktop to Captainbook (Statistics)
Did this answer your question?