Servidor MCP

El servidor MCP oficial de CrispHive. Apunte Claude, ChatGPT, Cursor o cualquier cliente MCP hacia CrispHive y podrá gestionar clientes, explorar su catálogo de servicios, consultar la disponibilidad real de agenda y reservar trabajos para un negocio de servicios de campo — cada endpoint REST de la Developer API, expuesto como una herramienta.

Es un servidor remoto alojado — nada que instalar ni ejecutar. Apunte su cliente al endpoint de abajo y quedará conectado.

https://api.crisphive.com/mcp

Requisitos

Cualquier cliente MCP que hable con servidores remotos por Streamable HTTP y pueda enviar un encabezado personalizado — claude.ai, Claude Desktop, Claude Code, ChatGPT, Gemini CLI, Cursor, VS Code, Windsurf, Cline, Zed, LM Studio y más. El transporte es sin estado (respuestas JSON planas — sin SSE, sin sesiones) y el servidor expone únicamente herramientas.

Instalación

Elija su cliente abajo para ver exactamente cómo conectarlo:

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"

Autenticación

Las solicitudes se autentican con una clave de API secreta enviada como token bearer — la misma clave que la API REST /v1. Cree las claves desde el panel de negocio de CrispHive. El prefijo de la clave decide con qué datos trabaja el agente:

chsk_live_… → datos live (producción).
chsk_test_… → datos de sandbox (prueba aislada). Un agente con una clave de prueba solo puede tocar datos de sandbox — la forma recomendada de dejarlo experimentar.

Mantenga la clave en el servidor y cárguela desde el entorno — nunca la incluya en el control de versiones ni distribuya una clave chsk_ en una app del lado del cliente.

OAuth 2.1 (sin clave de API)

¿Está creando un conector para claude.ai / ChatGPT — o cualquier producto donde sus usuarios aportan su propio negocio de CrispHive? El endpoint /mcp también es un servidor de autorización OAuth 2.1 completo: el propietario del negocio autoriza su agente en una pantalla de consentimiento y nunca se copia ninguna clave. Un cliente MCP conforme ejecuta todo el flujo automáticamente (normalmente no escribe nada de código OAuth), activado por un 401 que porta WWW-Authenticate: Bearer resource_metadata="…":

Paso	Solicitud
1. Descubrir el recurso	`GET /.well-known/oauth-protected-resource` (RFC 9728) → la URL del servidor de autorización
2. Descubrir el AS	`GET /.well-known/oauth-authorization-server` (RFC 8414) → endpoints; se requiere PKCE `S256`; grants `authorization_code` + `refresh_token`
3. Registrar	`POST /oauth/register` (RFC 7591 Dynamic Client Registration) → `client_id` (cliente público, sin secreto — PKCE es la prueba)
4. Autorizar	`GET /oauth/authorize?…` — el propietario del negocio inicia sesión en CrispHive y da su consentimiento
5. Intercambiar	`POST /oauth/token` (`grant_type=authorization_code`, `code`, `code_verifier`) → `{ access_token, refresh_token, expires_in }`
6. Renovar	`POST /oauth/token` (`grant_type=refresh_token`) → un par de tokens rotado (el refresh token anterior es de un solo uso)

A partir de ahí, llame a /mcp con Authorization: Bearer <access_token> — idéntico a la vía con clave de API. El token está vinculado al negocio, la región y el entorno del propietario que dio su consentimiento, de modo que un agente nunca puede alcanzar otro tenant ni cambiar entre live↔sandbox. Solicite un scope más restringido (códigos de permiso separados por espacios, p. ej. customers_view job_requests_view) para limitar al agente; omítalo para acceso completo al negocio. Los access tokens duran ~1 hora — use el refresh token para seguir conectado.

Herramientas

Hay 22 herramientas, una por cada operación de la API pública /v1 — con los mismos nombres que los métodos del SDK (listCustomers, createJobRequest, …), generadas a partir de la misma especificación OpenAPI para que REST y MCP nunca se desincronicen. Los parámetros de ruta/consulta y los campos del cuerpo de la solicitud se aplanan en un único objeto de argumentos por herramienta.

Grupo	Herramientas
Clientes sincronización con CRM, CRUD completo	`listCustomers` · `createCustomer` · `getCustomer` · `updateCustomer` · `deleteCustomer`
Reservas crear y seguir	`createJobRequest` · `listJobRequests` · `getJobRequest` · `getJobRequestTimeline` · `listJobRequestBookingWindows` · `listJobRequestChanges`
Catálogo solo lectura	`listJobTypes` · `getJobType` · `listSkills` · `listSkillCategories` · `listSkillsByCategory` · `listServiceAreas` · `getServiceArea`
Equipo y flota solo lectura	`listTechnicians` · `getTechnician` · `listVehicles` · `getVehicle`

Cada herramienta devuelve el sobre REST sin procesar — { error_code, message, data } — como texto; los agentes desenvuelven data en caso de éxito y leen error_code en caso de fallo.
Las claves restringidas se aplican sin cambios: una clave con alcance customers_view recibe un 403 de las herramientas de escritura.
Las herramientas de creación (createCustomer, createJobRequest) aceptan un idempotency_key opcional, reenviado como el encabezado Idempotency-Key — pase el mismo valor al reintentar para que un reintento nunca cree un duplicado.
Las entradas de encabezado también son argumentos: p. ej. listJobRequestBookingWindows toma x_timezone (una zona horaria IANA, enviada como el encabezado X-Timezone).
Cada herramienta declara un outputSchema y devuelve structuredContent (el sobre analizado) junto al texto, de modo que los clientes tipados pueden omitir el reanálisis.
Las sugerencias de comportamiento se establecen por herramienta — las lecturas llevan readOnlyHint y los borrados llevan destructiveHint, de modo que clientes como Claude pueden preguntar antes de ejecutar acciones destructivas.

Un flujo de agente típico se ve así:

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

Paginación

Las herramientas de listado aceptan page / limit y devuelven un objeto meta (per_page, current_page, total_pages), de modo que un agente puede recorrer grandes conjuntos de resultados una página a la vez.

Límites de tasa

Las solicitudes tienen límite de tasa por clave, compartido con REST: 240 por minuto. Ante un sobre 429, aplique backoff y reintente.

Errores

Cada herramienta devuelve el sobre de respuesta de CrispHive (como texto y como structuredContent): error_code es 0 en caso de éxito, o una cadena estable en caso de fallo (CUSTOMER_NOT_FOUND, API_KEY_INVALID, …). Compare por el código, nunca por el texto del mensaje. Una clave inválida o revocada devuelve HTTP 401 (API_KEY_INVALID) — corrija el encabezado y vuelva a conectar.

Notas del protocolo

Envíe por POST un mensaje JSON-RPC 2.0 (o un lote de como máximo 20) por solicitud; las respuestas son application/json, y las notificaciones se confirman con 202.
El servidor es sin estado — no se emite ni se requiere ningún id de sesión; GET /mcp devuelve 405 (no hay flujo de server-push).
Los argumentos UUID de la ruta se validan antes del despacho — un id que no es UUID devuelve un error de herramienta en banda, nunca una operación distinta.
Revisiones de protocolo aceptadas: 2025-06-18, 2025-03-26, 2024-11-05.

Documentación

Guías — empiece aquí por los conceptos y los flujos de reserva.
Referencia de la API — cada endpoint, argumento y esquema.
Para IA — la especificación OpenAPI más un arranque de asistente listo para pegar.
openapi.json — la especificación legible por máquina a partir de la cual se generan las herramientas.