--- name: crisphive-claude-setup description: "Walks a Crisphive customer step by step through connecting Crisphive to Claude. Add Crisphive to Claude as a custom connector, approve the sign-in in Rehearsal or Live, set tool approvals and book a confirmed job. Works on the Free plan. Use when the user wants to set up, test or troubleshoot Crisphive with Claude." --- # Set up Crisphive in Claude ## How to use this file (instructions for the AI assistant) You are helping a Crisphive customer connect Crisphive to **Claude**. The person you are talking to may not be technical and has probably not read the guide. Everything you need is in the guide below — follow it, do not improvise. 1. **Start by asking two things:** whether they already have a Crisphive account they can sign in to, and how far they have got (nothing yet, or which step). Skip the steps they have already done. 2. **Give ONE step at a time.** Name the exact page, button and field from the guide, and the exact value to type. Wait for them to say it is done (or to send a screenshot) before the next step. 3. **Ask for a screenshot when they are stuck** or when what they see does not match the guide. Screens change; if a label in the guide is not on their screen, say so plainly, describe what the step is trying to achieve, and help them find the closest equivalent. Never invent a button name. 4. **Secrets never go in this chat.** API keys (`chsk_…`), webhook signing secrets (`whsec_…`) and OAuth client secrets are pasted only into the platform field the guide names. If the user pastes one here, tell them to revoke it in Crisphive and create a new one. 5. **Start in Rehearsal (the sandbox).** Recommend test keys (`chsk_test_…`) and Rehearsal mode until the test at the end of the guide works. Only then explain how to switch to Live. 6. **Finish with the guide’s test.** The setup is done only when the test in the guide succeeds (for example a job appears in the Crisphive dashboard). If it fails, use the Troubleshooting and FAQ sections below. 7. **Stay inside this guide.** For anything it does not cover, point the user to the full page or to support@crisphive.com instead of guessing. Source page: https://docs.crisphive.com/docs/claude (last updated 2026-10-10). If the user asks, this file is generated from that page and is always in step with it. --- # The guide Follow these steps and the Crisphive connector will be working in your Claude account — signed in, pointed at the right data, and tested with a real confirmed booking — in about five minutes. A **connector** is a link that lets Claude use another service on your behalf. Crisphive’s connector speaks **MCP** (Model Context Protocol), the open format Claude uses to discover and call another service’s actions. You do not need to know anything about MCP to set it up. For what Claude can do once connected, see [Crisphive for Claude](https://crisphive.com/claude); for the full list of tools, see the [MCP reference](https://docs.crisphive.com/mcp#tools). If you see Crisphive in Claude’s connector directory, connecting from there skips Step 1 — continue at Step 2. Otherwise add Crisphive by URL as a **custom connector** (Step 1 below); it gives exactly the same connection. ## Ways to connect | Where you use Claude | How to connect | Sign-in | | --- | --- | --- | | claude.ai (web) | Customize → Connectors → + Add → Add custom connector (this guide) | Crisphive sign-in + Approve | | Claude Desktop | The same, in the Desktop app’s Customize → Connectors | Crisphive sign-in + Approve | | Claude mobile apps | Connect once on claude.ai or Desktop; the connector follows your Claude account | Done on web or Desktop | | Claude Code (terminal) | One command — see [Claude Code](https://docs.crisphive.com/docs/claude#claude-code) | Browser sign-in, or an API key | ## Before you start - **A Crisphive account** you can sign in to at `https://crisphive.com/app`, with at least one technician, a service area and working hours — Claude can only book times your team can work. - **Know who should approve.** The connection always acts as the person who clicks Approve, with that person’s current Crisphive role. For dispatch work that person should be an **Owner** or **Booking Coordinator**. See [Which role to connect with](https://docs.crisphive.com/docs/claude#roles). - **Any Claude plan.** The **Free** plan is enough for one custom connector. On Team and Enterprise an organization Owner adds the connector first. - **About 5 minutes.** No API key and nothing to install for claude.ai. - **Start in Rehearsal.** Rehearsal is your business’s sandbox: isolated test data — nothing there reaches a real customer. You choose the mode on the Crisphive approval page; see [Step 3](https://docs.crisphive.com/docs/claude#environment). A brand-new Claude account first asks how you plan to use Claude (**For personal use** / **With my team**), shows the plans (**Free** is enough), offers the desktop app (**Skip** is fine), shows a data setting under *Before your first chat* (**Continue**), and asks your name and the kind of work you do (**Set up later** is offered). ## Step 1 — Add Crisphive to Claude On a Claude **Team or Enterprise** plan, an organization Owner adds the connector once for everyone, with the same name and URL as below; members then open **Customize → Connectors**, find Crisphive and click **Connect** — continue at Step 2. On Free, Pro and Max you add it yourself: 1. **Open Claude’s connectors** — On **claude.ai**, click **Customize** in the left navigation, then the **Connectors** tab. 2. **Add a custom connector** — Click **+ Add** (top right), then **Add custom connector**. If the option is missing, your Claude organization does not allow custom connectors — see [Troubleshooting](https://docs.crisphive.com/docs/claude#troubleshooting). 3. **Enter the name and server URL** — **Name**: `Crisphive`. **MCP server URL**: `https://api.crisphive.com/mcp`. Click **Continue**. 4. **Leave the detected settings and click Add** — The next step shows **Authentication** (**Sign in now** is selected and marked *Detected*) and **OAuth client** (**Register automatically** is selected and marked *Detected*). Claude picked the right settings itself: no API key and no client ID are needed. Do not choose **No sign-in**. Click **Add**. Screen in Claude: **Add custom connector** (`claude.ai`) 1. In Customize → Connectors, click + Add, then Add custom connector. — click **Add custom connector** 2. Type Crisphive as the name. — **Name**: `Crisphive` 3. Paste https://api.crisphive.com/mcp as the MCP server URL, then click Continue. — **MCP server URL**: `https://api.crisphive.com/mcp` 4. Leave Authentication on Sign in now and OAuth client on Register automatically — Claude detected both — and click Add. — click **Add** ## Step 2 — Sign in to Crisphive and approve Adding the connector does not connect it yet: Claude now shows *You’re not connected to Crisphive yet.* with a **Connect** button. Connecting uses **OAuth**: a standard way to let one app act for you in another without you copying a password or key. You confirm once, Claude receives a token, and you can revoke it at any time. 1. **Click Connect** — The Crisphive approval page opens in the same tab. If you are signed out of Crisphive, sign in with your usual email or phone code first; you come back to the approval page afterwards. 2. **Check the business, the mode and who you are** — The page is titled **Authorize Claude** and reads *Claude wants to access your Crisphive business*. It shows your business name, the mode (**Rehearsal** or **Live**) and *Signed in as …*, with a **Switch** link if the business or account is wrong. In Rehearsal it says *Claude will only see Rehearsal (test) data — not your real jobs, customers or team.* and offers **Connect Live instead**. 3. **Check what you are approving** — Under *This will allow Claude to* it shows **Access and manage the business data made available to this integration**; *See what data is shared* gives the detail. 4. **Click Approve** — You are back on Claude’s connector page, which now lists *Your connectors — Crisphive* with a **Disconnect** button and the tool permissions (Step 4). **Deny** shares nothing. Screen in Crisphive: **Authorize Claude** (`crisphive.com/oauth/consent`) 1. Check the business and the mode. In Rehearsal, Claude will only see Rehearsal (test) data. Use Switch for another business or account, or Connect Live instead for live data. — **Mode**: `Rehearsal` 2. Read what Claude will be allowed to do, then click Approve. You return to Claude, now connected. — click **Approve** ## Step 3 — Point it at Live or Rehearsal data Crisphive keeps two separate copies of your business: **Live** (real customers, jobs and team) and **Rehearsal** (the sandbox: isolated test data — bookings there never reach a real customer and send no real notifications). Claude has no setting for this. **The connection uses the mode shown on the Authorize Claude page when you click Approve**, and keeps it. 1. **For a Rehearsal (test) connection** — Approve while the page shows **Rehearsal** and *Claude will only see Rehearsal (test) data*. If it shows Live, switch the Crisphive dashboard to Rehearsal (**Rehearsal | Live** switch in the left sidebar → **Switch**) and click Connect in Claude again. 2. **For a live connection** — Click **Connect Live instead** on the approval page, check that it now shows **Live**, then approve. 3. **To switch later** — Disconnect Crisphive in Claude, click Connect again and approve in the other mode. ## Step 4 — Choose which tools run without asking After you approve, the connector page shows **Tool permissions** — *Choose when Claude is allowed to use these tools.* — with two groups, **Read-only tools** and **Write/delete tools**, each with its tool count. Both start at **Needs approval**, so Claude asks before every Crisphive tool. 1. **Answer Claude’s prompt in the chat** — Before each tool Claude shows *Claude wants to use from Crisphive* with **Deny** (Esc), **Allow once** and **Always allow**. 2. **Allow reads, keep approval on writes** — A safe setup: answer **Always allow** for tools starting with `list`, `get` and `preview` (they change nothing), and **Allow once** for everything that creates, updates, deletes or commits. On a live connection, never always-allow `commitEmergencyReschedule`, `commitJobRequestMove`, `commitAbsenceResolve` or any `delete…` tool. ## Step 5 — Test the connection Do this on a **Rehearsal** connection. Use an address inside one of your service areas. 613-555-01xx numbers are reserved for fiction, and Crisphive never texts them. 1. **Start a new chat and ask for a booking** — Type, for example: *“Using Crisphive: book a furnace inspection for Sam Tremblay (phone +16135550188) at 300 Bank Street, Ottawa, K2P 1X8, next Thursday at 2 pm, and confirm it.”* If Claude does not use Crisphive, check that the connector is switched on for the chat. 2. **Allow the tool calls** — Answer each *Claude wants to use … from Crisphive* prompt with **Allow once** or **Always allow**. 3. **Read Claude’s answer** — Success: the job is **booked and confirmed**, with a reference such as `REQ-CA-…`, the date and time, and a technician. If your business has no matching job type, Claude books **General** and puts the service (e.g. *Furnace inspection*) in the description. Claude also says how it read a relative date such as *next Thursday* — check it. 4. **Check in the dashboard** — In `https://crisphive.com/app`, still in **Rehearsal**, the job shows **Confirmed** with a technician assigned. Under **Settings → Developer → MCP connections** (`/app/settings/developer/mcp-servers`), Claude is listed under **Connected AI apps**. > **Trust the dashboard over Claude’s summary.** In our test Claude said it had *created a new customer record*, but Crisphive had matched the existing customer by phone number: Crisphive does not create a second customer with the same phone. ## Which role to connect with Claude can do exactly what the approving person can do in the Crisphive dashboard, re-checked on every request. Change their role and Claude’s access changes on its next call; remove or suspend them and the connection stops at once. | Approved by | Result | | --- | --- | | Owner | Full access to the business, as in the dashboard. | | Booking Coordinator | The schedule and customers. The usual choice for a dispatcher’s Claude. | | Administrator | Rehearsal (sandbox) only by default; in live data it can do nothing until the Owner grants modules in the role matrix. | | Technician | Can read the job type list, but **not** the business job board, any job’s details or timeline, matching views or another technician’s schedule (`403 FORBIDDEN`). This is the role, not a setting you can widen. | ## Ready-to-copy settings ``` Name: Crisphive MCP server URL: https://api.crisphive.com/mcp Authentication: Sign in now (detected) OAuth client: Register automatically (detected) — no client ID or secret Smaller tool sets (optional, same sign-in, same permissions): https://api.crisphive.com/mcp/dispatch jobs, moves, emergencies, sick calls, roster reads https://api.crisphive.com/mcp/crm customers and their bookings ``` Use the plain `/mcp` URL unless you want Claude to see fewer tools. A smaller set only changes which tools Claude is *shown*; what it is *allowed* to do is still the approving person’s role. ## Claude Desktop and mobile - **Claude Desktop:** add the connector in Desktop’s own **Customize → Connectors**, exactly as in Step 1. Sign-in from Desktop has been tested end to end on production. If you added Crisphive on claude.ai and Desktop does not show it as connected, add it again directly in Desktop — this is a Claude Desktop behaviour, not a Crisphive one. - **Claude mobile apps:** connectors belong to your Claude account. Connect on claude.ai or Desktop first, then use Crisphive from the mobile app. ## Claude Code ```bash # Browser sign-in (acts as you, same consent page as above) claude mcp add --transport http crisphive https://api.crisphive.com/mcp # Or with a sandbox API key instead of sign-in claude mcp add --transport http crisphive https://api.crisphive.com/mcp \ --header "Authorization: Bearer chsk_test_YOUR_KEY" ``` An **API key** is a secret password for software, created in Crisphive under **Settings → Developer → API Keys**; a `chsk_test_` key only reaches sandbox data. Other editors and agents (Cursor, VS Code, Gemini CLI, Windsurf…) are covered in the [MCP install guide](https://docs.crisphive.com/mcp#install). ## Keep the connection alive - **While you use it,** Claude refreshes its access automatically. After 30 days without any use, the connection lapses. - **Whatever the use,** it ends 90 days after you approved it. To change that, open **Settings → Developer → MCP connections**, click **Set lifetime** on Claude’s row, enter **Lifetime (days)** (1–365) and click **Save**. The days count from the original approval, not from today. - **You are warned:** the business’s Owners and Administrators are emailed 14 days before it ends. - **To renew,** click Connect in Claude and approve again. A connection that has already ended cannot be extended, only re-approved. ## Disconnect Claude 1. **From Crisphive — cuts off Claude for the whole business** — Open **Settings → Developer → MCP connections**. Under **Connected AI apps**, click **Disconnect** on Claude’s row, then **Disconnect** again to confirm. This revokes *every* active grant Claude holds for your business — if several people connected their own Claude (the row shows how many active grants), all of them are disconnected. The list shows only the mode the dashboard is in — switch to Rehearsal to find a Rehearsal connection. 2. **From Claude** — Open **Customize → Connectors**, open Crisphive, and disconnect or remove it. This affects only your own Claude account. 3. **Expect a short tail** — An access token Claude already holds keeps working for up to one hour after a disconnect in Crisphive; nothing new is issued. Removing or suspending the member stops the connection on its very next request. ## Troubleshooting | Symptom | Cause | Fix | | --- | --- | --- | | No **Add custom connector** option | Your Claude plan or organization does not allow custom connectors. | Use a plan that supports them, or ask your Claude organization admin to allow or add the connector. | | Claude says *You’re not connected to Crisphive yet.* | The connector was added but never connected, or the approval page was closed without **Approve**. | Click **Connect** on the connector page and approve. | | Claude says it created a new customer, but you expected an existing one | Claude’s wording. Crisphive matches an existing customer by phone number and does not create a duplicate. | Check **Customers** in the dashboard; the job sits on the existing record. | | The job was booked as **General** | Your business has no job type matching the request, so the default type was used and the service went into the description. | Add the job type, with a default duration, in the Crisphive dashboard. | | Crisphive page says *Invalid authorization request* | The sign-in link was incomplete or expired. | Close the window and click Connect in Claude again. | | Connected on claude.ai, but Desktop shows it disconnected | Claude Desktop does not always pick up a connector added on the web. | Add the connector directly in Claude Desktop. | | Claude finds no customers or jobs, or different ones than you see | The connection is in the other mode (Live vs Rehearsal) than your dashboard. | Disconnect, click Connect again and approve in the mode you want (**Connect Live instead** for live data). | | `403 FORBIDDEN` when asking about jobs or the schedule | The person who approved is a Technician, or their role lacks job management. | Have an Owner or Booking Coordinator connect instead. | | Approve fails with `access_denied` | Your membership is suspended, or the request asked for a permission your role does not hold. | Ask the Owner to reactivate you or adjust your role, then connect again. | | Claude asks you to reconnect; `OAUTH_GRANT_EXPIRED` | The connection reached its lifetime (90 days by default) or was unused for 30 days. | Click Connect and approve again; raise the lifetime with **Set lifetime** if needed. | | Claude disconnects unexpectedly soon after a refresh | A refresh token was used again more than 30 seconds after it was replaced, which Crisphive treats as theft and revokes the whole connection. | Connect and approve again. | | Test booking “saved but not confirmed”, or `JOB_REQUEST_NO_TECHNICIAN_AVAILABLE` | No technician fits that exact time (skills, service area, working hours, other jobs). | Ask Claude for the nearest open times. Do not book the same job again — it is already in the coordinator queue. | | `JOB_REQUEST_QUOTE_NOT_SCHEDULABLE` | No technician can take the job in any window asked for; `data.reason` says why (e.g. `outside_service_area`, `outside_working_hours`). | Choose another day, or fix the cause in the dashboard (service area, working hours, technician skills). | | `PHONE_INVALID` | The phone number is not a real number in international form. | Give it with the country code, e.g. `+1 613 555 0177`. | | `JOB_REQUEST_INVALID_INPUT` with `data.means_locally` | A time carried a timezone offset that disagrees with your business’s local time. | Ask for the time in your business’s local time, without an offset. | | `ABSENCE_RESOLVE_TIME_OFF_REQUIRED` | A sick-call commit needs a time-off record covering every day of the absence. | Ask Claude to record the time off first, then commit again. | | A commit fails because the schedule changed (e.g. `ABSENCE_RESOLVE_PLAN_DRIFTED`) | Someone changed the board between the preview and the commit. | Ask Claude for a fresh preview and approve that one. | | `429` | More than 240 requests a minute on this key or connection, shared with REST — about 120 MCP tool calls a minute, since each tool call also makes one REST request. | Wait a minute; split large imports into smaller requests. | ## Go live - Disconnect the Rehearsal connection, click Connect in Claude, choose **Connect Live instead** on the approval page and approve — as an Owner or Booking Coordinator. - On live data, a confirmed job notifies the customer and technician, and a committed move, emergency or sick-call plan notifies every customer whose visit changed. Keep approval on for those tools (Step 4). - Note the *Expires* date in **MCP connections** (90 days by default) and renew before it, or raise the lifetime. - Using Claude Code with a key? Swap `chsk_test_…` for a `chsk_live_…` key. Keys expire too (30 days by default, up to 365, set when created; Owners and Administrators are emailed 7 days before). Revoke a key with **Revoke access** on its row under **API keys**. ## Related guides and reference - [AI assistants overview](https://docs.crisphive.com/docs/ai-assistants) — Claude, ChatGPT and any other MCP client - [ChatGPT](https://docs.crisphive.com/docs/chatgpt) — the Crisphive plugin, or a developer-mode connector - [MCP server reference](https://docs.crisphive.com/mcp) — every tool, the tool profiles and client setup - [Voice agents overview](https://docs.crisphive.com/docs/voice-agents) — the voice tool set and booking rules - [Automation platforms overview](https://docs.crisphive.com/docs/automation-platforms) — what every automation integration shares ## FAQ **Do I need an API key to connect Claude?** No. On claude.ai and Claude Desktop you sign in to Crisphive and click Approve. An API key is only an option for Claude Code and other developer tools. **Do I need a paid Claude plan?** No. The Free plan lets you add one custom connector, which is all Crisphive needs. **How do I connect Claude to my sandbox (Rehearsal) instead of live data?** Approve while the Authorize Claude page shows **Rehearsal**. The connection keeps the mode it was approved in; to change it, disconnect and approve again in the other mode (**Connect Live instead** for live data). **Why can my technician’s Claude not see the schedule?** The connection acts as the person who approved it, and the Technician role cannot read the business-wide job board. Have an Owner or Booking Coordinator connect for dispatch work. **Why did my Crisphive connector stop working in Claude?** Usually the connection reached its lifetime (90 days after approval by default) or sat unused for 30 days, or the person who approved was removed, suspended or changed role. Reconnect and approve; check **Settings → Developer → MCP connections** for the expiry date. **Can two people in my business each connect their own Claude?** Yes. Each person approves with their own Crisphive sign-in, and each connection acts with that person’s role. In **MCP connections** they appear as one Claude row with several active grants; disconnecting that row disconnects all of them, so to remove one person’s access, have them disconnect in their own Claude settings. **Where do I see which AI apps are connected to my business?** In the Crisphive dashboard under **Settings → Developer → MCP connections**, section **Connected AI apps**. It lists the current mode only, so switch to Rehearsal to see Rehearsal connections.