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.

https://api.crisphive.com/mcp

Zuerst ausprobieren

Verbinden Sie sich (ein chsk_test_-Sandbox-Schlüssel genügt) und fügen Sie einen dieser Prompts direkt in Ihren Agenten ein — dieselben Prompts stehen auf jedem Crisphive-Listing, hier sehen Sie also genau die First-Run-Erfahrung von überall (die Prompts selbst bleiben englisch):

• Auftragserstellung — “Schedule a 2-hour HVAC job at 145 Laurier Ave W tomorrow for Marie Tremblay, 613-555-0142.” createCustomer → listJobRequestBookingWindows → createJobRequest → quoteJobRequest → confirmJobRequest
• Notfall-Einschub — “Emergency plumbing job now at 99 Bank St for David Okafor (613-555-0198) — show me what gets rescheduled.” listEmergencyCandidates → previewEmergencyReschedule → commitEmergencyReschedule
• Tagesüberblick — “Outline my day tomorrow and flag anything at risk.” listJobRequests → getTechnicianSchedule
• Freie-Zeiten-Suche — “Find 3 hours this week for a bike ride with my wife without risking any jobs.” getTechnicianSchedule → der Agent findet den Spielraum im Zeitplan selbst

Dieselbe Anfrage, Ihre Sprache

Der Engine ist egal, wer spricht — Disponent, Inhaber oder Entwickler steuern dieselben Tools. Hier dieselben Anfragen, formuliert wie jede Rolle sie wirklich tippen würde (die Prompts bleiben englisch):

So funktioniert es

Jeder Prompt oben nimmt denselben Weg: Claude übersetzt natürliche Sprache in Tool-Aufrufe, der MCP-Server steuert dieselbe öffentliche REST-API wie jeder andere Client, und ein deterministischer Solver berechnet den Zeitplan — kein LLM im Optimierungskern. Die Ergebnisse werden in das System of Record des Unternehmens zurückgespielt.

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:

# 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="…":

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. Der Agent handelt als die Person, die ihn genehmigt hat — er kann nie mehr tun, als dieses Mitglied im Dashboard könnte, und er funktioniert nicht mehr, wenn die Person entfernt oder gesperrt wird. Fordern Sie einen engeren scope an (durch Leerzeichen getrennte Berechtigungscodes, z. B. customers_view job_view), um ihn weiter einzuschränken; lassen Sie ihn weg, gilt alles, was dieses Mitglied tun darf. Access-Tokens leben ~1 Stunde — nutzen Sie das Refresh-Token, um verbunden zu bleiben. Dasselbe Token funktioniert auch gegen die REST-API /v1 — siehe Multi-Tenant-Integration bauen.

Verbindungslaufzeit

Eine MCP-Verbindung wird von zwei unabhängigen Uhren bestimmt. Ein täglich genutzter Agent wird nie planmäßig getrennt; einer, der vergessen wird, läuft von selbst ab.

• Inaktivitätsfenster — 30 Tage. Jede Token-Erneuerung stellt ein neues Refresh-Token aus, das weitere 30 Tage gilt. Nutzen Sie die Verbindung weiter, verlängert sie sich unbegrenzt; bleiben Sie 30 Tage inaktiv, erlischt sie.
• Absolute Obergrenze — 90 Tage. Unabhängig von der Aktivität endet eine Verbindung 90 Tage, nachdem der Unternehmensinhaber sie genehmigt hat. Das Unternehmen kann dies pro Verbindung unter Developers → MCP connections auf einen Wert von 1 bis 365 Tagen setzen; der Countdown wird ab der ursprünglichen Genehmigung gemessen, nicht ab der Änderung.

Läuft eine der beiden Uhren ab, schlägt das Erneuern fehl, und der Inhaber muss die App erneut über den Consent-Screen genehmigen. Behandeln Sie jede fehlgeschlagene Erneuerung als „Autorisierungsablauf neu starten“, niemals als wiederholbaren Fehler. Die Inhaber und Administratoren des Unternehmens werden 14 Tage bevor eine Verbindung abläuft per E-Mail benachrichtigt — die erneute Genehmigung erfordert den Inhaber im Browser, daher kommt die Warnung früher als bei Schlüsseln.

Tools

Es gibt 46 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.

• 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. Ein Schlüssel, der seine Laufzeit überschritten hat, liefert 401 mit API_KEY_EXPIRED — erstellen Sie einen Ersatzschlüssel. Eine OAuth-Verbindung, deren Grant abgelaufen ist, liefert OAUTH_GRANT_EXPIRED — führen Sie den Autorisierungsablauf über den Consent-Screen erneut aus.

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.