Serveur MCP

Le serveur MCP officiel de CrispHive. Pointez Claude, ChatGPT, Cursor ou n’importe quel client MCP vers CrispHive et il peut gérer les clients, parcourir votre catalogue de services, vérifier la disponibilité de planification réelle et réserver des interventions pour une entreprise de services sur le terrain — chaque endpoint REST de l’API Developer, exposé sous forme d’outil.

C’est un serveur distant hébergé — rien à installer ni à exécuter. Pointez votre client vers le point de terminaison ci-dessous et vous êtes connecté.

https://api.crisphive.com/mcp

Prérequis

Tout client MCP prenant en charge les serveurs distants via Streamable HTTP et capable d’envoyer un en-tête personnalisé — claude.ai, Claude Desktop, Claude Code, ChatGPT, Gemini CLI, Cursor, VS Code, Windsurf, Cline, Zed, LM Studio, et plus encore. Le transport est sans état (réponses JSON simples — pas de SSE, pas de sessions) et le serveur n’expose que des outils.

Installation

Choisissez votre client ci-dessous pour voir exactement comment le connecter :

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"

Authentification

Les requêtes s’authentifient avec une clé API secrète envoyée comme jeton bearer — la même clé que l’API REST /v1. Créez vos clés depuis le tableau de bord entreprise de CrispHive. Le préfixe de la clé décide des données avec lesquelles l’agent travaille :

chsk_live_… → données live (production).
chsk_test_… → données du bac à sable (test isolé). Un agent doté d’une clé de test ne peut jamais toucher que les données du bac à sable — c’est la façon recommandée de le laisser expérimenter.

Gardez la clé côté serveur et chargez-la depuis l’environnement — ne la commitez jamais et n’expédiez jamais une clé chsk_ dans une application côté client.

OAuth 2.1 (sans clé API)

Vous construisez un connecteur claude.ai / ChatGPT — ou tout produit où vos utilisateurs apportent leur propre entreprise CrispHive ? Le point de terminaison /mcp est aussi un serveur d’autorisation OAuth 2.1 complet : le propriétaire de l’entreprise autorise votre agent sur un écran de consentement et aucune clé n’est jamais copiée. Un client MCP conforme exécute tout le flux automatiquement (vous n’écrivez normalement aucun code OAuth), déclenché par un 401 portant WWW-Authenticate: Bearer resource_metadata="…" :

Étape	Requête
1. Découvrir la ressource	`GET /.well-known/oauth-protected-resource` (RFC 9728) → l’URL du serveur d’autorisation
2. Découvrir le serveur d’autorisation	`GET /.well-known/oauth-authorization-server` (RFC 8414) → endpoints ; PKCE `S256` requis ; grants `authorization_code` + `refresh_token`
3. Enregistrer	`POST /oauth/register` (RFC 7591 Dynamic Client Registration) → `client_id` (client public, sans secret — PKCE est la preuve)
4. Autoriser	`GET /oauth/authorize?…` — le propriétaire de l’entreprise se connecte à CrispHive et donne son consentement
5. Échanger	`POST /oauth/token` (`grant_type=authorization_code`, `code`, `code_verifier`) → `{ access_token, refresh_token, expires_in }`
6. Rafraîchir	`POST /oauth/token` (`grant_type=refresh_token`) → une paire de jetons renouvelée (l’ancien refresh token est à usage unique)

À partir de là, appelez /mcp avec Authorization: Bearer <access_token> — à l’identique du parcours avec clé API. Le jeton est lié à l’entreprise, la région et l’environnement du propriétaire consentant, si bien qu’un agent ne peut jamais atteindre un autre locataire ni basculer live↔sandbox. Demandez une scope plus étroite (codes de permission séparés par des espaces, p. ex. customers_view job_requests_view) pour restreindre l’agent ; omettez-la pour un accès complet à l’entreprise. Les jetons d’accès vivent environ 1 heure — utilisez le refresh token pour rester connecté.

Outils

Il existe 22 outils, un par opération de l’API publique /v1 — les mêmes noms que les méthodes du SDK (listCustomers, createJobRequest, …), générés à partir de la même spécification OpenAPI pour que REST et MCP ne divergent jamais. Les paramètres de chemin/requête et les champs du corps de requête sont aplatis en un unique objet d’arguments par outil.

Groupe	Outils
Clients synchronisation CRM, CRUD complet	`listCustomers` · `createCustomer` · `getCustomer` · `updateCustomer` · `deleteCustomer`
Réservations créer & suivre	`createJobRequest` · `listJobRequests` · `getJobRequest` · `getJobRequestTimeline` · `listJobRequestBookingWindows` · `listJobRequestChanges`
Catalogue lecture seule	`listJobTypes` · `getJobType` · `listSkills` · `listSkillCategories` · `listSkillsByCategory` · `listServiceAreas` · `getServiceArea`
Équipe & flotte lecture seule	`listTechnicians` · `getTechnician` · `listVehicles` · `getVehicle`

Chaque outil renvoie l’enveloppe REST brute — { error_code, message, data } — sous forme de texte ; les agents extraient data en cas de succès et lisent error_code en cas d’échec.
Les clés restreintes s’appliquent sans changement : une clé limitée à customers_view reçoit un 403 des outils d’écriture.
Les outils de création (createCustomer, createJobRequest) acceptent un idempotency_key optionnel, transmis via l’en-tête Idempotency-Key — passez la même valeur lors d’une nouvelle tentative pour qu’un réessai ne crée jamais de doublon.
Les entrées d’en-tête sont aussi des arguments : p. ex. listJobRequestBookingWindows prend x_timezone (un fuseau horaire IANA, envoyé via l’en-tête X-Timezone).
Chaque outil déclare un outputSchema et renvoie structuredContent (l’enveloppe analysée) en plus du texte, de sorte que les clients typés peuvent éviter une nouvelle analyse.
Des indices de comportement sont définis par outil — les lectures portent readOnlyHint et les suppressions portent destructiveHint, si bien que des clients comme Claude peuvent demander confirmation avant d’exécuter des actions destructrices.

Un flux d’agent typique ressemble à ceci :

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

Pagination

Les outils de liste acceptent page / limit et renvoient un objet meta (per_page, current_page, total_pages), de sorte qu’un agent peut parcourir de grands ensembles de résultats page par page.

Limites de débit

Les requêtes sont limitées en débit par clé, partagées avec REST : 240 par minute. Sur une enveloppe 429, temporisez et réessayez.

Erreurs

Chaque outil renvoie l’enveloppe de réponse CrispHive (sous forme de texte et de structuredContent) : error_code vaut 0 en cas de succès, ou une chaîne stable en cas d’échec (CUSTOMER_NOT_FOUND, API_KEY_INVALID, …). Basez-vous sur le code, jamais sur le texte du message. Une clé invalide ou révoquée renvoie un HTTP 401 (API_KEY_INVALID) — corrigez l’en-tête et reconnectez-vous.

Notes de protocole

Envoyez en POST un message JSON-RPC 2.0 (ou un lot d’au plus 20) par requête ; les réponses sont en application/json, et les notifications sont acquittées par un 202.
Le serveur est sans état — aucun identifiant de session n’est émis ni requis ; GET /mcp renvoie 405 (il n’y a pas de flux de push serveur).
Les arguments de chemin UUID sont validés avant l’acheminement — un id non-UUID renvoie une erreur d’outil en bande, jamais une opération différente.
Révisions de protocole acceptées : 2025-06-18, 2025-03-26, 2024-11-05.

Documentation

Guides — commencez ici pour les concepts et les flux de réservation.
Référence de l’API — chaque endpoint, argument et schéma.
Pour l’IA — la spécification OpenAPI plus un amorçage d’assistant prêt à coller.
openapi.json — la spécification lisible par machine à partir de laquelle les outils sont générés.