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.

https://api.crisphive.com/mcp

Prueba esto primero

Conéctate (basta una clave sandbox chsk_test_) y pega cualquiera de estos prompts directamente en tu agente — los mismos prompts aparecen en todos los listados de Crisphive, así que esta es exactamente la primera experiencia en todas partes (los prompts se mantienen en inglés):

• Creación de trabajos — “Schedule a 2-hour HVAC job at 145 Laurier Ave W tomorrow for Marie Tremblay, 613-555-0142.” createCustomer → listJobRequestBookingWindows → createJobRequest → quoteJobRequest → confirmJobRequest
• Inserción de emergencia — “Emergency plumbing job now at 99 Bank St for David Okafor (613-555-0198) — show me what gets rescheduled.” listEmergencyCandidates → previewEmergencyReschedule → commitEmergencyReschedule
• Resumen del día — “Outline my day tomorrow and flag anything at risk.” listJobRequests → getTechnicianSchedule
• Búsqueda de disponibilidad — “Find 3 hours this week for a bike ride with my wife without risking any jobs.” getTechnicianSchedule → el agente razona sobre la holgura de la agenda

La misma petición, en tu idioma

Al motor no le importa quién habla — un coordinador, el dueño o un desarrollador manejan las mismas herramientas. Las mismas peticiones, redactadas como cada rol las escribiría de verdad (los prompts se mantienen en inglés):

Cómo funciona

Cada prompt de arriba recorre el mismo camino: Claude convierte el lenguaje natural en llamadas a herramientas, el servidor MCP opera la misma API REST pública que cualquier otro cliente, y un solver determinista calcula la agenda — sin ningún LLM en el núcleo de optimización. Los resultados se sincronizan con el sistema de registro del negocio.

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:

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

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. El agente actúa como la persona que lo aprobó — nunca puede hacer más de lo que ese miembro podría hacer en el panel, y deja de funcionar si se lo elimina o suspende. Solicite un scope más restringido (códigos de permiso separados por espacios, p. ej. customers_view job_view) para limitarlo aún más; omitirlo significa todo lo que ese miembro puede hacer. Los access tokens duran ~1 hora — use el refresh token para seguir conectado. El mismo token también funciona con la API REST /v1 — vea Construya una integración multi-tenant.

Duración de la conexión

Una conexión MCP se rige por dos relojes independientes. Un agente en uso diario nunca se desconecta de forma programada; uno que queda olvidado expira por sí solo.

• Ventana de inactividad — 30 días. Cada refresco de token emite un nuevo refresh token válido por otros 30 días. Siga usando la conexión y se prorroga indefinidamente; permanezca inactivo 30 días y caduca.
• Tope absoluto — 90 días. Independientemente de la actividad, una conexión termina 90 días después de que el propietario del negocio la aprobó. El negocio puede fijarlo en cualquier valor de 1 a 365 días por conexión en Developers → MCP connections; la cuenta atrás se mide desde la aprobación original, no desde el cambio.

Cuando cualquiera de los dos relojes se agota, el refresco falla y el propietario debe aprobar la aplicación de nuevo desde la pantalla de consentimiento. Trate cualquier refresco fallido como «reiniciar el flujo de autorización», nunca como un error reintentable. Los Propietarios y Administradores del negocio reciben un correo 14 días antes de que una conexión expire — volver a aprobar requiere al propietario en un navegador, por lo que el aviso llega antes que en el caso de las claves.

Herramientas

Hay 46 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.

• 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. Una clave que superó su duración devuelve 401 con API_KEY_EXPIRED — cree una clave de reemplazo. Una conexión OAuth cuyo grant se agotó devuelve OAUTH_GRANT_EXPIRED — vuelva a ejecutar el flujo de autorización desde la pantalla de consentimiento.

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.