@servicialo/mcp-server

English version

La interfaz MCP a nivel de protocolo para el estándar Servicialo — la capa de destino para servicios humanos en la era de agentes de IA. HTTP hizo los documentos direccionables. Servicialo hace los servicios direccionables. MCP y A2A son el transporte. Servicialo es el destino al que los agentes llegan.

Este paquete es la interfaz MCP a nivel de protocolo para cualquier backend compatible con Servicialo — no un conector a una plataforma específica. Coordinalo es la implementación de referencia (y el default), pero puedes conectar tu propio backend.

Arquitectura

@servicialo/mcp-server  →  interfaz MCP a nivel de protocolo
        ↓ se conecta a cualquier backend compatible con Servicialo
Coordinalo              →  implementación de referencia (default)
Tu implementación       →  trae tu propio backend

El Problema

Los agentes de IA pueden navegar la web, escribir código y mantener conversaciones. Pero pídele a uno que reserve una sesión de kinesiología, verifique que ocurrió, y procese el pago — y se desmorona.

Hoy, cada plataforma es un silo. No hay estándar para:

• Descubrimiento — qué prestador, en qué organización, ofrece lo que necesito?

• Identidad — en nombre de quién actúa este agente, y qué está autorizado a hacer?

• Ciclo de vida — en qué estado está este servicio? Quién confirmó? Quién asistió?

• Prueba de entrega — ocurrió realmente la sesión? Por cuánto tiempo? Dónde?

• Liquidación — cuánto, a quién, bajo qué términos contractuales?

Sin un protocolo compartido, cada integración es artesanal. Cada conexión agente-plataforma es un API custom. Esto no escala.

Qué es Servicialo

Servicialo es un protocolo abierto, no una plataforma. Define cómo los servicios profesionales se mueven a través de su ciclo de vida — desde el descubrimiento hasta el pago — de una forma que cualquier agente de IA o plataforma puede implementar.

La relación es como HTTP con Apache, o SMTP con Gmail: Servicialo define las reglas, las implementaciones les dan vida.

El protocolo modela cada servicio a través de 8 dimensiones, 9 estados del ciclo de vida, 6 flujos de excepción y 7 principios fundamentales — universales entre verticales (salud, legal, educación, servicios domiciliarios):

Solicitado → Agendado → Confirmado → En Curso → Completado → Documentado → Facturado → Cobrado → Verificado

Cualquier servicio, en cualquier vertical, sigue esta secuencia. La lógica específica del vertical vive dentro de cada estado, pero la máquina de estados es invariante.

Qué Hace Este MCP Server

Este paquete expone el protocolo Servicialo como 34 herramientas MCP organizadas por las 7 fases del ciclo de vida de un servicio (0–6, incluyendo resolución DNS), más herramientas de gestión de recursos y administración del resolver. Un agente no llama endpoints por entidad de base de datos — sigue el flujo natural de coordinar un servicio.

Fase 0 — Resolución DNS (3 herramientas públicas, sin autenticación)

Fase 1 — Descubrimiento (6 herramientas públicas, sin autenticación)

Fase 2 — Entender (2 herramientas)

Fase 3 — Comprometer (3 herramientas)

Fase 4 — Ciclo de Vida (4 herramientas)

Fase 5 — Verificar Entrega (3 herramientas)

Fase 6 — Cerrar (4 herramientas)

Gestión de Recursos (6 herramientas)

Administración del Resolver (3 herramientas)

Quickstart — 5 pasos para estar en la red

Paso 1. Instalar el servidor MCP

npx -y @servicialo/mcp-server

Modo descubrimiento — 10 herramientas públicas, sin credenciales. Pruébalo de inmediato:

{
  "tool": "registry.search",
  "arguments": { "vertical": "kinesiologia", "location": "santiago" }
}

Paso 2. Crear tu organización

Registra tu organización en coordinalo.com/signup. Coordinalo es la implementación de referencia del protocolo Servicialo.

Paso 3. Obtener credenciales MCP

En Coordinalo: Settings → Servicialo → Generar credenciales MCP. Obtendrás dos valores:

• SERVICIALO_ORG_ID — slug de tu organización (ej: clinica-dental-sur)

• SERVICIALO_API_KEY — bearer token para autenticación

Paso 4. Configurar el cliente MCP

Agregar a la configuración de Claude Desktop, Cursor o cualquier cliente MCP:

{
  "mcpServers": {
    "servicialo": {
      "command": "npx",
      "args": ["-y", "@servicialo/mcp-server"],
      "env": {
        "SERVICIALO_API_KEY": "<tu_api_key>",
        "SERVICIALO_ORG_ID": "<tu_org_slug>"
      }
    }
  }
}

Omitir el bloque env para modo solo-descubrimiento (10 herramientas públicas).

Paso 5. Publicar en la red Servicialo

En Coordinalo: Settings → Servicialo → Publicar. Tu organización aparece en servicialo.com/network y es descubrible por otros agentes.

Tip: Un agente puede obtener estos 5 pasos como JSON estructurado llamando la herramienta docs.quickstart.

Red / Network

La red Servicialo es el registro global de organizaciones que implementan el protocolo. Cada nodo autenticado envía un heartbeat periódico, y cualquier agente puede descubrir organizaciones por país, vertical y puntaje de confianza.

• Explorar la red: servicialo.com/network

• Buscar por vertical: registry.search({ vertical: "kinesiologia", country: "cl" })

• Resolver un org: resolve.lookup({ org_slug: "clinica-dental-sur" })

Credenciales

SERVICIALO_API_KEY y SERVICIALO_ORG_ID deben configurarse juntas. Si solo una está presente, el servidor cae a modo descubrimiento con un warning.

Las credenciales se obtienen en coordinalo.com → Settings → Servicialo → Generar credenciales MCP.

Conectar una implementación propia

Este MCP server soporta cualquier backend compatible con Servicialo a través de la capa de adaptadores pluggable. Dos adaptadores están incluidos:

• coordinalo (default) — se conecta a un backend Coordinalo/Digitalo con rutas org-scoped bajo /api/organizations/{orgId}.

• http — se conecta a cualquier implementación que exponga los endpoints canónicos de HTTP_PROFILE.md bajo /v1/*.

3 pasos para conectar tu implementación

Paso 1. Implementar los endpoints REST definidos en HTTP_PROFILE.md en tu plataforma.

Paso 2. Configurar el MCP server para usar el adaptador HTTP:

SERVICIALO_ADAPTER=http \
SERVICIALO_BASE_URL=https://tu-plataforma.com \
SERVICIALO_API_KEY=tu_key \
npx -y @servicialo/mcp-server

Paso 3. Agregar a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "servicialo": {
      "command": "npx",
      "args": ["-y", "@servicialo/mcp-server"],
      "env": {
        "SERVICIALO_ADAPTER": "http",
        "SERVICIALO_BASE_URL": "https://tu-plataforma.com",
        "SERVICIALO_API_KEY": "tu_api_key",
        "SERVICIALO_ORG_ID": "tu_org_id"
      }
    }
  }
}

El adaptador HTTP traduce las rutas internas a endpoints canónicos /v1/* y envía el contexto de organización via el header X-Servicialo-Org. Consulta HTTP_PROFILE.md para el contrato REST completo.

Modelo de Agencia Delegada

El protocolo trata a los agentes de IA como actores de primera clase — pero nunca confía en ellos implícitamente. Cada acción de agente requiere un ServiceMandate: una delegación explícita de capacidad de un humano principal a un agente.

Cómo funciona

1. Un humano (profesional, paciente u organización) emite un mandato a un agente

2. El mandato especifica para quién actúa el agente, qué puede hacer (scopes), y por cuánto tiempo

3. En cada tool call, el MCP server valida el mandato contra 8 checks antes de ejecutar

4. Cada acción produce una entrada de auditoría — éxito o fallo

Ejemplo de mandato

{
  "mandate_id": "550e8400-e29b-41d4-a716-446655440000",
  "principal_id": "dra_barbara",
  "principal_type": "professional",
  "agent_id": "agent_booking_bot",
  "agent_name": "Asistente de Agendamiento",
  "acting_for": "professional",
  "context": "org:clinica-kinesia",
  "scopes": ["schedule:read", "schedule:write", "patient:write"],
  "constraints": {
    "max_actions_per_day": 50,
    "allowed_hours": {
      "start": "08:00",
      "end": "20:00",
      "timezone": "America/Santiago"
    },
    "require_confirmation_above": {
      "amount": 100000,
      "currency": "CLP"
    }
  },
  "issued_at": "2026-03-01T00:00:00Z",
  "expires_at": "2026-06-01T00:00:00Z",
  "status": "active"
}

Uso de mandatos en tool calls

Cuando actor.type es "agent", incluir el mandate_id:

{
  "tool": "scheduling.book",
  "arguments": {
    "service_id": "srv_123",
    "provider_id": "prov_111",
    "client_id": "cli_789",
    "starts_at": "2026-03-03T10:00:00",
    "actor": {
      "type": "agent",
      "id": "agent_booking_bot",
      "mandate_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Los 8 checks de validación

Cada tool call de un agente se valida contra:

Actores no-agente (client, provider, organization) no pasan por validación de mandato.

Descubrimiento de Prestadores

Los agentes pueden buscar en el registro y hacer matching de prestadores con las necesidades de un paciente usando consultas estructuradas.

Buscar en el registro

{
  "tool": "registry.search",
  "arguments": {
    "vertical": "kinesiologia",
    "location": "santiago",
    "country": "cl"
  }
}

Retorna organizaciones que coinciden con sus servicios y prestadores.

Consultar disponibilidad

{
  "tool": "scheduling.check_availability",
  "arguments": {
    "org_slug": "clinica-kinesia",
    "service_id": "srv_rehab_pelvica",
    "provider_id": "prov_111",
    "date_from": "2026-03-10",
    "date_to": "2026-03-14"
  }
}

El scheduler de 3 variables verifica disponibilidad de prestador, cliente y recurso físico simultáneamente.

Ejemplo de punta a punta

1. registry.search({ vertical: "kinesiologia", location: "santiago" })
   → encuentra org "clinica-kinesia"

2. services.list({ org_slug: "clinica-kinesia" })
   → lista servicios disponibles

3. scheduling.check_availability({ org_slug: "clinica-kinesia", date_from: "2026-03-10", date_to: "2026-03-14" })
   → retorna slots disponibles

4. contract.get({ service_id: "srv_123", org_id: "org_456" })
   → cancelación: 0% si >24h, 50% si 2-24h, 100% si <2h
   → evidencia requerida: check_in + check_out + registro_clinico

5. clients.get_or_create({ email: "maria@mail.com", name: "Maria", last_name: "Lopez" })
   → client_id: "cli_789"

6. scheduling.book({ service_id: "srv_123", provider_id: "prov_111", client_id: "cli_789", starts_at: "2026-03-12T10:00:00" })
   → session_id: "ses_001", estado: "solicitado"

7. scheduling.confirm({ session_id: "ses_001" })
   → estado: "confirmado"

8. delivery.checkin({ session_id: "ses_001", location: { lat: -33.45, lng: -70.66 } })
   → estado: "en_curso"

9. delivery.checkout({ session_id: "ses_001", location: { lat: -33.45, lng: -70.66 } })
   → estado: "entregado", duración: 42min

10. documentation.create({ session_id: "ses_001", content: "Sesión de rehabilitación de piso pélvico..." })
    → estado: "documentado"

11. payments.create_sale({ client_id: "cli_789", service_id: "srv_123", unit_price: 35000 })
    → sale_id: "sale_001", estado: "cobrado"

12. lifecycle.transition({ session_id: "ses_001", to_state: "verified" })
    → estado: "verificado" ✓

Especificación del Protocolo

La especificación completa del protocolo Servicialo está disponible en:

• Repositorio: github.com/servicialo/protocol

• Sitio web: servicialo.com

• Versión estable actual: 0.9

• JSON Schemas: service.schema.json, service-order.schema.json, service-mandate.schema.json, resolution.schema.json, servicialo-config.schema.json

La spec cubre las 8 dimensiones del servicio, 9 estados de ciclo de vida, 6 flujos de excepción, 7 principios fundamentales, la arquitectura de dos entidades (Servicio atómico + Orden de Servicio), el Modelo de Agencia Delegada, resolución DNS, e interoperabilidad A2A.

Implementación de Referencia

Digitalo es la primera implementación en producción del protocolo Servicialo, operando en salud en Chile. Implementa el ciclo de vida completo — desde descubrimiento de prestadores hasta liquidación de pagos — y sirve como terreno de validación para la evolución del protocolo.

Este MCP server se conecta a cualquier backend compatible con Servicialo a través de SERVICIALO_BASE_URL. Digitalo es uno de esos backends. El protocolo está diseñado para que cualquier CRM, HIS, o plataforma lo implemente como un nodo soberano.

Contribuir al Protocolo

Servicialo sigue versionado semántico para la especificación del protocolo:

• Patch (0.7.x) — clarificaciones, correcciones de typos, adiciones no-breaking

• Minor (0.x.0) — nuevos campos opcionales, nuevas definiciones de herramientas, nuevos flujos de excepción

• Major (x.0.0) — cambios breaking a schemas, máquina de estados, o semántica core

Cómo proponer cambios

1. Abrir un issue describiendo el problema y la solución propuesta

2. Para cambios significativos, escribir un RFC en spec/ con el número de sección que afecta

3. Los cambios al protocolo requieren al menos una implementación de referencia antes de merge

4. Los cambios a schemas deben incluir JSON Schema actualizado y tipos Zod en el MCP server

Áreas buscando input activamente

• Requisitos de evidencia específicos por vertical (más allá de salud)

• Soporte multi-idioma para nombres de estados del ciclo de vida

• Federación inter-nodo (cómo dos implementaciones Servicialo interoperan)

• Patrones de Agent SDK para Python y TypeScript

Telemetría

Al iniciar, el MCP server envía un único POST anónimo a https://servicialo.com/api/telemetry/instance con:

{
  "event": "node_initialized",
  "version": "0.9.8",
  "node_id": "a1b2c3d4-...",
  "ts": 1711300000000
}

Esto es todo lo que se envía. No se transmite información de organización, API keys, datos de pacientes ni ningún identificador personal. La IP se hashea (SHA-256) en el servidor antes de almacenarse. El ping es fire-and-forget: si falla, el error se descarta silenciosamente y nunca bloquea la operación del servidor.

La primera vez que se ejecuta con telemetría activa, el servidor imprime un aviso en stderr indicando qué se envía y cómo desactivarlo.

Desactivar telemetría

SERVICIALO_TELEMETRY=false npx -y @servicialo/mcp-server

O en la configuración MCP:

{
  "env": {
    "SERVICIALO_TELEMETRY": "false"
  }
}

Más detalles: servicialo.com/docs/telemetry

Únete a la red

Al instalar @servicialo/mcp-server, tu nodo se registra automáticamente en la telemetría de la red. Esto ayuda al ecosistema a medir adopción real del protocolo — sin recopilar datos personales ni de tus clientes.

La telemetría reporta únicamente: versión del paquete, un UUID de nodo persistente, y un hash de IP (para geolocalización aproximada — no almacenamos IPs). Puedes desactivarla en cualquier momento con SERVICIALO_TELEMETRY=false.

Verificación de implementador

Si operas una implementación propia del protocolo, puedes identificar tu nodo y solicitar el estatus de implementador verificado. Configura estas variables de entorno opcionales:

SERVICIALO_IMPL_NAME="Mi Plataforma"    # Nombre de tu implementación
SERVICIALO_IMPL_URL="https://example.com" # Tu sitio web o repositorio
SERVICIALO_IMPL_CONTACT="admin@example.com" # Email de contacto (hasheado, nunca se muestra)

Cuando un nuevo IMPL_NAME aparece por primera vez, el equipo de Servicialo recibe una notificación y revisa manualmente. Una vez verificado, tu implementación aparece en servicialo.com/implementors con un badge de verificado.

Si no configuras estas variables, tu nodo permanece completamente anónimo — sin cambios en el comportamiento.

Licencia

Apache-2.0 — cualquier implementación, comercial o no, es bienvenida. Ver LICENSE.