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 Desktop (or 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.

  • Claude Desktop installed (or any client that supports 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., "Claude Desktop — 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 the Configuration snippet ready to paste.

Step 2 — Paste the configuration into Claude Desktop

  1. Copy the Configuration block.

  2. Open Claude Desktop → settings → Developer → Edit Config.

  3. Paste inside the mcpServers object alongside any existing servers.

  4. Save and restart Claude Desktop.

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 Claude Desktop.

  • 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?