Crisphive MCP

Crisphive MCP

The official MCP (Model Context Protocol) server for the Crisphive API — agentic AI scheduling infrastructure for field operations.

Lets AI agents — Claude, ChatGPT, Gemini, Cursor or any MCP client — match schedules between customers and businesses and route crews to jobs by location, skills, and real-time availability: job booking & appointment scheduling, work-order tracking, availability from a live dispatch & scheduling engine, customer (CRM) sync, service catalogs, technician & crew rosters, geographic service territories and fleet — for trades and home services such as HVAC, plumbing, electrical, cleaning, appliance repair and property maintenance. Scheduling is constraint-based on a deterministic solver: the agent handles the conversation, the solver makes the decision — same inputs, same plan, never an LLM guessing at a calendar. Hosted remote server; nothing to install or run (this repository holds the documentation and registry manifest).

https://api.crisphive.com/mcp

Try these first

Connect (a chsk_test_ sandbox key is enough), then paste any of these straight into your agent:

1. Job creation — *"Schedule a 2-hour HVAC job at 145 Laurier Ave W tomorrow for Marie Tremblay, 613-555-0142."* (createCustomer → listJobRequestBookingWindows → createJobRequest → quoteJobRequest → confirmJobRequest)
2. Emergency insertion — *"Emergency plumbing job now at 99 Bank St for David Okafor (613-555-0198) — show me what gets rescheduled."* (listEmergencyCandidates → previewEmergencyReschedule → commitEmergencyReschedule)
3. Daily outline — *"Outline my day tomorrow and flag anything at risk."* (listJobRequests → getTechnicianSchedule)

. Sick call — *"Dmitri called in sick for tomorrow — re-staff his jobs without moving any customer's appointment."* (previewAbsenceResolve → commitAbsenceResolve)

The same prompts appear on every Crisphive listing and docs page, so what you see here is exactly the first-run experience everywhere.

→ Full overview, tool table and one-click connect: https://crisphive.com/claude

Requirements

Any MCP client that supports remote servers over Streamable HTTP — claude.ai, Claude Desktop, Claude Code, ChatGPT, Gemini CLI, Cursor, VS Code, Windsurf, Cline, Zed, LM Studio, ….

Installation

claude.ai / Claude Desktop (OAuth — no key needed)

Settings → Connectors → Add custom connector, paste https://api.crisphive.com/mcp. Sign in as the Crisphive business owner when the consent screen opens. *(Custom connectors require a Claude plan that supports them.)*

Claude Code

# OAuth (you'll be prompted to authorize in the browser)

claude mcp add --transport http crisphive https://api.crisphive.com/mcp

or with an API key (sandbox key shown — safe to experiment)

claude mcp add --transport http crisphive https://api.crisphive.com/mcp \ --header "Authorization: Bearer chsk_test_YOUR_KEY"

Cursor

Or add to .cursor/mcp.json:

{

"mcpServers": { "crisphive": { "url": "https://api.crisphive.com/mcp" } } }

VS Code

code --add-mcp '{"name":"crisphive","url":"https://api.crisphive.com/mcp"}'

ChatGPT

Settings → Connectors (developer mode) → add MCP server with URL https://api.crisphive.com/mcp (OAuth).

Gemini CLI

Add to ~/.gemini/settings.json (note: Gemini CLI uses httpUrl for Streamable HTTP servers):

{

"mcpServers": { "crisphive": { "httpUrl": "https://api.crisphive.com/mcp", "headers": { "Authorization": "Bearer chsk_test_YOUR_KEY" } } } }

Other MCP clients (Windsurf, Cline, Zed, LM Studio, …)

Most clients accept the standard remote-server shape:

{

"mcpServers": { "crisphive": { "url": "https://api.crisphive.com/mcp", "headers": { "Authorization": "Bearer chsk_test_YOUR_KEY" } } } }

Only the URL field name varies in a few clients:

Clients that only speak stdio can bridge with mcp-remote:

{

"mcpServers": { "crisphive": { "command": "npx", "args": ["-y", "mcp-remote", "https://api.crisphive.com/mcp"] } } }

Local server (npm — @crisphive/mcp)

This repository also ships a thin local stdio server: the same 67 tools (same names, same schemas — generated from the same /v1 OpenAPI spec as the hosted endpoint), where each call is an HTTPS request to the Crisphive API with your key. No business logic runs locally.

{

"mcpServers": { "crisphive": { "command": "npx", "args": ["-y", "@crisphive/mcp"], "env": { "CRISPHIVE_API_KEY": "chsk_test_YOUR_KEY" } } } }

Environment variables:

Prefer the hosted remote server (https://api.crisphive.com/mcp) when your client supports it — OAuth, no key handling, always current. The local package exists for stdio-only clients and self-hosted setups.

Developing in this repo: npm ci && npm test. The tool registry (src/tools.generated.json) is generated — npm run generate refreshes it from the live spec; CI fails if it drifts from /v1.

Authentication

Every request is authenticated with a secret API key sent as a bearer token. Create keys from your Crisphive business dashboard. The key prefix selects the data environment:

• chsk_live_… → live (production) data
• chsk_test_… → sandbox (isolated test) data

Load keys from the environment — never commit them.

Keys expire. The lifetime is chosen when the key is created — 30 days by default, up to 365 — and is fixed for that key's life; it cannot be extended later. To renew, create a *second* key, point your agent at it, then revoke the first: a business can hold several active keys at once, so the changeover has no downtime and needs no special endpoint (the same procedure AWS documents for access keys). Read expires_at from the dashboard or the key API and schedule the swap. An aged-out key fails with API_KEY_EXPIRED, distinct from API_KEY_INVALID, so you can alert on a missed renewal separately from a revocation.

Crisphive emails the business's owners 7 days before a key expires (14 days for an OAuth connection), so an expiry should not be a surprise — but the mail goes to the business, not necessarily to you, so track expires_at yourself. A key deliberately created for less than 7 days gets no advance notice; it would have arrived at creation.

The MCP endpoint additionally supports OAuth 2.1 for end-user connectors (claude.ai, ChatGPT, …): the business owner authorizes your agent on a consent screen and no key is ever handled. A compliant MCP client runs the whole flow automatically — discovery, dynamic client registration, authorization code + PKCE. Full flow, scopes and token lifetimes: docs/integration.md.

Tools

67 tools, one per operation of the public /v1 API — same names as the SDK methods (listCustomers, createJobRequest, …), derived from the same OpenAPI spec so REST and MCP never drift. Full reference: docs/tools.md.

Typical agent flow:

listSkills / listJobTypes                → discover reference IDs

createCustomer → { customer_id } listJobRequestBookingWindows → offer only the returned windows createJobRequest → booking created quoteJobRequest → confirmJobRequest → scheduled (auto or forced technician) (quote answers 409 JOB_REQUEST_QUOTE_NOT_SCHEDULABLE when the customer would see no slot — agree a new time, or resend with force: true) getJobRequest / listJobRequestChanges → track status

One-call flow for a phone call or an automation (voice agents: connect to https://api.crisphive.com/mcp?profile=voice for a small tool set):

listCustomers (phone: "+16135550188")    → is the caller already a customer?

bookAndConfirmJobRequest → booked + scheduled, or confirmed:false + refusal (the job then waits in the coordinator's queue)

Emergency (P0) flow:

createJobRequest (priority: "p0") → quoteJobRequest

listEmergencyCandidates → ranked techs + crew_recommendation previewEmergencyReschedule → what moves (or reassigns) commitEmergencyReschedule → inserted + auto-confirmed (or preview with an inline job probe, then bookAndConfirmJobRequest with priority p0 + emergency{dispatch: "now"} books and commits in one call)

Sick-call flow (a technician is out — re-