MCP-Server

Der offizielle MCP-Server für CrispHive. Richten Sie Claude, ChatGPT, Cursor oder einen beliebigen MCP-Client auf CrispHive aus, und er kann Kunden verwalten, Ihren Servicekatalog durchsuchen, echte Terminverfügbarkeit prüfen und Jobs buchen für ein Außendienst-Unternehmen — jeder REST-Endpunkt der Developer-API, bereitgestellt als Tool.

Es ist ein gehosteter Remote-Server — nichts zu installieren oder auszuführen. Richten Sie Ihren Client auf den untenstehenden Endpunkt aus, und Sie sind verbunden.

https://api.crisphive.com/mcp

Voraussetzungen

Jeder MCP-Client, der Remote-Server über Streamable HTTP unterstützt und einen benutzerdefinierten Header senden kann — claude.ai, Claude Desktop, Claude Code, ChatGPT, Gemini CLI, Cursor, VS Code, Windsurf, Cline, Zed, LM Studio und mehr. Der Transport ist zustandslos (einfache JSON-Antworten — kein SSE, keine Sessions), und der Server stellt ausschließlich Tools bereit.

Installation

Wählen Sie unten Ihren Client, um genau zu sehen, wie Sie ihn verbinden:

Run one command. Omit the header to authorize in your browser (OAuth), or pass an API key to skip the browser step:

# OAuth — you'll be prompted to authorize in the browser
claude mcp add --transport http crisphive https://api.crisphive.com/mcp

# …or pass an API key to skip the browser step
claude mcp add --transport http crisphive https://api.crisphive.com/mcp \
  --header "Authorization: Bearer chsk_test_YOUR_KEY"

Authentifizierung

Anfragen authentifizieren sich mit einem geheimen API-Schlüssel, der als Bearer-Token gesendet wird — derselbe Schlüssel wie für die REST-/v1-API. Erstellen Sie Schlüssel in Ihrem CrispHive-Unternehmens-Dashboard. Das Schlüsselpräfix entscheidet, mit welchen Daten der Agent arbeitet:

chsk_live_… → Live-Daten (Produktion).
chsk_test_… → Sandbox-Daten (isolierter Test). Ein Agent mit einem Test-Schlüssel kann immer nur auf Sandbox-Daten zugreifen — die empfohlene Art, ihn experimentieren zu lassen.

Bewahren Sie den Schlüssel serverseitig auf und laden Sie ihn aus der Umgebung — committen Sie ihn niemals und liefern Sie einen chsk_-Schlüssel nie in einer clientseitigen App aus.

OAuth 2.1 (kein API-Schlüssel)

Sie bauen einen claude.ai-/ChatGPT-Connector — oder ein beliebiges Produkt, bei dem Ihre Nutzer ihr eigenes CrispHive-Unternehmen mitbringen? Der /mcp-Endpunkt ist zugleich ein vollständiger OAuth-2.1-Authorization-Server: Der Unternehmensinhaber autorisiert Ihren Agenten über einen Consent-Bildschirm, und es wird nie ein Schlüssel kopiert. Ein konformer MCP-Client durchläuft den gesamten Ablauf automatisch (in der Regel schreiben Sie keinen OAuth-Code), ausgelöst durch ein 401 mit WWW-Authenticate: Bearer resource_metadata="…":

Schritt	Anfrage
1. Ressource ermitteln	`GET /.well-known/oauth-protected-resource` (RFC 9728) → die URL des Authorization-Servers
2. Den AS ermitteln	`GET /.well-known/oauth-authorization-server` (RFC 8414) → Endpunkte; PKCE `S256` erforderlich; Grants `authorization_code` + `refresh_token`
3. Registrieren	`POST /oauth/register` (RFC 7591 Dynamic Client Registration) → `client_id` (öffentlicher Client, kein Secret — PKCE ist der Nachweis)
4. Autorisieren	`GET /oauth/authorize?…` — der Unternehmensinhaber meldet sich bei CrispHive an und erteilt seine Zustimmung
5. Austauschen	`POST /oauth/token` (`grant_type=authorization_code`, `code`, `code_verifier`) → `{ access_token, refresh_token, expires_in }`
6. Erneuern	`POST /oauth/token` (`grant_type=refresh_token`) → ein rotiertes Token-Paar (das alte Refresh-Token ist einmalig nutzbar)

Ab dann rufen Sie /mcp mit Authorization: Bearer <access_token> auf — identisch zum API-Schlüssel-Pfad. Das Token ist an das Unternehmen, die Region und die Umgebung des zustimmenden Inhabers gebunden, sodass ein Agent niemals einen anderen Mandanten erreichen oder zwischen Live↔Sandbox wechseln kann. Fordern Sie einen engeren scope an (durch Leerzeichen getrennte Berechtigungscodes, z. B. customers_view job_requests_view), um den Agenten einzuschränken; lassen Sie ihn weg für vollen Unternehmenszugriff. Access-Tokens leben ~1 Stunde — nutzen Sie das Refresh-Token, um verbunden zu bleiben.

Tools

Es gibt 22 Tools, eines pro Operation der öffentlichen /v1-API — dieselben Namen wie die SDK-Methoden (listCustomers, createJobRequest, …), generiert aus derselben OpenAPI-Spezifikation, sodass REST und MCP nie auseinanderdriften. Pfad-/Query-Parameter und Request-Body-Felder werden pro Tool zu einem einzigen Argumentobjekt zusammengefasst.

Gruppe	Tools
Kunden CRM-Sync, vollständiges CRUD	`listCustomers` · `createCustomer` · `getCustomer` · `updateCustomer` · `deleteCustomer`
Buchungen erstellen & verfolgen	`createJobRequest` · `listJobRequests` · `getJobRequest` · `getJobRequestTimeline` · `listJobRequestBookingWindows` · `listJobRequestChanges`
Katalog schreibgeschützt	`listJobTypes` · `getJobType` · `listSkills` · `listSkillCategories` · `listSkillsByCategory` · `listServiceAreas` · `getServiceArea`
Team & Fuhrpark schreibgeschützt	`listTechnicians` · `getTechnician` · `listVehicles` · `getVehicle`

Jedes Tool liefert das rohe REST-Envelope zurück — { error_code, message, data } — als Text; Agenten entpacken bei Erfolg data und lesen bei Fehler error_code.
Eingeschränkte Schlüssel gelten unverändert: Ein auf customers_view eingeschränkter Schlüssel erhält von Schreib-Tools ein 403.
Create-Tools (createCustomer, createJobRequest) akzeptieren ein optionales idempotency_key, das als Idempotency-Key-Header weitergereicht wird — übergeben Sie beim erneuten Versuch denselben Wert, damit ein wiederholter Aufruf nie ein Duplikat erzeugt.
Header-Eingaben sind ebenfalls Argumente: z. B. nimmt listJobRequestBookingWindows das Argument x_timezone (eine IANA-Zeitzone, gesendet als X-Timezone-Header).
Jedes Tool deklariert ein outputSchema und liefert neben dem Text auch structuredContent (das geparste Envelope), sodass typisierte Clients erneutes Parsen überspringen können.
Verhaltenshinweise werden pro Tool gesetzt — Lesevorgänge tragen readOnlyHint und Löschvorgänge destructiveHint, sodass Clients wie Claude vor dem Ausführen destruktiver Aktionen nachfragen können.

Ein typischer Agenten-Ablauf sieht so aus:

listSkills / listJobTypes                → discover reference IDs
createCustomer                           → { customer_id }
listJobRequestBookingWindows             → offer only the returned windows
createJobRequest                         → booking created
getJobRequest / listJobRequestChanges    → track status

Paginierung

Listen-Tools akzeptieren page / limit und liefern ein meta-Objekt (per_page, current_page, total_pages) zurück, sodass ein Agent große Ergebnismengen seitenweise durchlaufen kann.

Rate-Limits

Anfragen sind pro Schlüssel rate-limitiert, geteilt mit REST: 240 pro Minute. Bei einem 429-Envelope warten Sie ab und versuchen es erneut.

Fehler

Jedes Tool liefert das CrispHive-Response-Envelope zurück (als Text und als structuredContent): error_code ist 0 bei Erfolg oder ein stabiler String bei Fehler (CUSTOMER_NOT_FOUND, API_KEY_INVALID, …). Prüfen Sie auf den Code, niemals auf den Meldungstext. Ein ungültiger oder widerrufener Schlüssel liefert HTTP 401 (API_KEY_INVALID) — korrigieren Sie den Header und verbinden Sie sich erneut.

Protokoll-Hinweise

POSTen Sie eine JSON-RPC-2.0-Nachricht (oder einen Batch von höchstens 20) pro Anfrage; Antworten sind application/json, und Notifications werden mit 202 quittiert.
Der Server ist zustandslos — es wird keine Session-ID ausgestellt oder benötigt; GET /mcp liefert 405 (es gibt keinen Server-Push-Stream).
UUID-Pfadargumente werden vor dem Dispatch validiert — eine Nicht-UUID-ID liefert einen In-Band-Tool-Fehler, niemals eine andere Operation.
Akzeptierte Protokollrevisionen: 2025-06-18, 2025-03-26, 2024-11-05.

Dokumentation

Anleitungen — beginnen Sie hier für die Konzepte und Buchungsabläufe.
API-Referenz — jeder Endpunkt, jedes Argument und jedes Schema.
Für KI — die OpenAPI-Spezifikation plus ein einsatzbereiter Assistenten-Bootstrap zum Einfügen.
openapi.json — die maschinenlesbare Spezifikation, aus der die Tools generiert werden.