@crisphive/mcp

Crisphive MCP

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

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. Hosted remote server; nothing to install or run (this repository holds the documentation and registry manifest).

https://api.crisphive.com/mcp

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:

Client	Config file	URL field
Cline / Roo Code	cline_mcp_settings.json	url
Windsurf	~/.codeium/windsurf/mcp_config.json	serverUrl
Gemini CLI	~/.gemini/settings.json	httpUrl
Zed	settings.json → context_servers	url

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 43 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:

Variable	Required	Meaning
CRISPHIVE_API_KEY	for tool calls	chsk_live_… = production data, chsk_test_… = isolated sandbox. Create keys in the dashboard (Developers → API keys).
CRISPHIVE_BASE_URL	no	API origin override (default https://api.crisphive.com).

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.

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

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

Group	Tools
Customers (CRM sync, full CRUD)	listCustomers · createCustomer · getCustomer · updateCustomer · deleteCustomer
Bookings (create & track)	createJobRequest · listJobRequests · getJobRequest · getJobRequestTimeline · listJobRequestBookingWindows · listJobRequestChanges
Catalog (read-only)	listJobTypes · getJobType · listSkills · listSkillCategories · listSkillsByCategory · listServiceAreas · getServiceArea
Team & fleet (reads)	listTechnicians · getTechnician · listVehicles · getVehicle
Team roster management (HR-system sync)	createTechnician · updateTechnician · deleteTechnician · replaceTechnicianBuddies · replaceTechnicianLeads · replaceTechnicianVehicles · replaceTechnicianServiceAreas · replaceTechnicianSkills · listTechnicianSkills
Matching & scheduling (read-only, engine-computed)	listMatchingSlots · listCrewCandidates · getTechnicianSchedule · listNearbyTechnicians
Scheduling actions (drive the schedule)	quoteJobRequest · confirmJobRequest · previewJobRequestMove · commitJobRequestMove
Priority & emergency dispatch (P0–P3, SLA, cascade)	updateJobPriority · listEmergencyCandidates · previewEmergencyReschedule · commitEmergencyReschedule

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)
getJobRequest / listJobRequestChanges    → track status

Emergency (P0) flow:

createJobRequest (priority: "p0") → quoteJobRequest
listEmergencyCandidates                  → ranked techs + crew_recommendation
previewEmergencyReschedule               → what moves (or reassigns)
commitEmergencyReschedule                → inserted + auto-confirmed

Pagination

List tools accept page / limit and return a meta object (total, count, per_page, current_page, total_pages).

Idempotency

Create/commit tools (createCustomer, createTechnician, createJobRequest, confirmJobRequest, commitJobRequestMove, commitEmergencyReschedule) accept an idempotency_key argument so retries never create a duplicate — pass the same value when retrying.

Errors

Every tool returns the Crisphive response envelope (as text and as structuredContent): error_code is 0 on success, a stable string on failure (CUSTOMER_NOT_FOUND, API_KEY_INVALID, …). Match codes, never message strings.

Documentation

• Docs: https://docs.crisphive.com
• MCP: https://docs.crisphive.com/mcp
• API reference: https://docs.crisphive.com/technical-reference
• Webhooks: https://docs.crisphive.com/webhook
• For AI (OpenAPI spec + assistant bootstrap): https://docs.crisphive.com/for-ai
• Client integration guide: docs/integration.md
• Tool reference: docs/tools.md

Privacy & support

• Privacy policy: https://crisphive.com/privacy-policy — Crisphive processes the business data reachable through the API (customers, bookings, technicians, fleet) solely to operate the Service; it does not sell personal information. Data is retained while the account is active and shared only with service providers/sub-processors as necessary. An agent connected over MCP acts on behalf of the authorizing business and is scoped to that business's data, environment (live vs sandbox) and granted permissions.
• Support: [e-mail]

License

MIT