Especificación
El protocolo, en una página
Referencia de lectura de la especificación. La fuente normativa es el repositorio: PROTOCOL.md (completa), SPEC.md (quick ref), los JSON Schemas y protocol/manifest.yaml (superficie legible por máquinas).
◆ Protocolo v0.10 (draft)◆ @servicialo/mcp-server v0.9.13◆ Apache-2.0
§1 — Objetos
Objetos canónicos
El protocolo define objetos y eventos legibles por máquinas. Cada uno declara si tiene JSON Schema publicado o si por ahora se especifica en prosa.
| Objeto | Qué representa | Schema |
|---|---|---|
| Service Offer | Lo que una organización ofrece: tipo, descripción, requisitos, duración estimada, condiciones indicativas. | prosa / derivado |
| Service (wire object) | Objeto wire que representa una instancia de Service Delivery, modelada en 8 dimensiones. El nombre se conserva por compatibilidad. Puede existir sola o dentro de una Orden. | service.schema.json |
| Service Order | El acuerdo entre las partes: alcance, cliente, beneficiario, proveedor, pagador, precio, políticas, vigencia, esquema de pagos. | service-order.schema.json |
| Service Delivery | La instancia atómica ejecutada: qué se entregó, quién, a quién, cuándo, dónde o por qué canal, con qué resultado. En el wire actual se representa con el objeto Service. | prosa / derivado |
| Evidence Event | Registros y atestaciones que respaldan afirmaciones sobre una entrega: confirmaciones, documentos, firmas, timestamps. | evidence/base.schema.json |
| Settlement Event | Movimientos financieros asociados: factura, cargo, pago, devolución, contracargo, conciliación. | prosa / derivado |
| ServiceMandate | Delegación explícita, acotada y revocable de un principal humano a un agente IA. | service-mandate.schema.json |
| Proof of Serviceborrador | El expediente verificable que vincula lo acordado, lo entregado, la evidencia y la liquidación. | prosa / derivado |
Service Offer
lo ofrecido
↓
Service Order
lo acordado
↓
Service Delivery
lo entregado
↙↘
Evidence Events
lo observado
Settlement Events
lo liquidado
evolucionan de forma independiente
↘↙
Proof of Service
el expediente
§2 — Dimensiones
Las 8 dimensiones de un Service
Los campos mínimos para que un agente entienda y coordine un servicio.
| # | Dimensión | Qué captura | Campos |
|---|---|---|---|
| 1 | Identidad (qué) | La actividad o resultado que se entrega | type, vertical, name, duration_minutes, requirements |
| 2 | Proveedor (quién entrega) | Profesional o entidad que entrega | provider.id, credentials, trust_score, organization_id |
| 3 | Cliente (quién recibe) | Beneficiario; el pagador se separa explícitamente | client.id, client.payer_id |
| 4 | Agenda (cuándo) | Ventana temporal del servicio | requested_at, scheduled_for, duration_expected |
| 5 | Ubicación (dónde) | Física o virtual; puede referenciar un Resource | type, address, resource_id, coordinates |
| 6 | Ciclo (estados) | Posición en las dimensiones de estado — entrega, evidencia, aceptación y liquidación, cada una con ciclo propio | current_state, transitions[], exceptions[] |
| 7 | Evidencia (prueba) | Cómo se respalda que ocurrió | checkin, checkout, duration_actual, evidence[], data_sensitivity |
| 8 | Cobro (liquidación) | Liquidación financiera, independiente del ciclo de entrega | amount, payer, status, payment_id, tax_document |
§3 — Estados
Dimensiones ortogonales y camino feliz
El protocolo no establece un orden total entre entrega, evidencia, aceptación y liquidación: cada dimensión conserva su propio ciclo de vida. Una implementación puede presentar una experiencia lineal; la interoperabilidad se evalúa por dimensión (PROTOCOL.md §6.0).
Core requerido (6)
requested → scheduled → confirmed → in_progress → completed → documented
Extensión financiera (3, opcional)
invoiced → collected → verified
Excepción (5)
cancelled · disputed · reassigning · rescheduling · partial
Tracks paralelos ya presentes en el Core
El estado financiero corre en su propio track (
billing.status: pending | charged | invoiced | paid | disputed), y la Orden de Servicio tiene su propio ciclo (draft → proposed → negotiating → active → paused → completed → cancelled).La proyección ortogonal completa (fulfillment / evidence / acceptance / financial / order) se formaliza en la extensión state-dimensionsborrador
Camino feliz (vista de 9 hitos)
requested → scheduled → confirmed → in_progress → completed → documented → invoiced → collected → verified
Nota de implementación: el enum del tool
lifecycle.transition de la implementación de referencia usa delivered/charged en lugar de completed/invoiced+collected — divergencia conocida, documentada en el manifest.§4 — Excepciones
Flujos de excepción
Seis flujos de primera clase. Cualquiera puede sacar la coordinación del camino feliz sin romper el protocolo.
| Excepción | Desde | Hacia | Regla clave |
|---|---|---|---|
| Inasistencia del cliente | confirmed | cancelled (no_show) | Penalidad según política; libera el horario del proveedor |
| Inasistencia del proveedor | confirmed | reassigning → scheduled | Reasignación automática; notificar al cliente |
| Cancelación | pre-entrega | cancelled | Aplica política de cancelación según tiempo restante |
| Disputa de calidad | completed | disputed | Congela el cobro; solicita evidencia; resuelve a verified o cancelled |
| Reagendamiento | scheduled/confirmed | rescheduling → scheduled | Mantiene proveedor cuando es posible; maneja conflictos de recurso |
| Entrega parcial | in_progress | partial | Documenta lo entregado; ajusta el cobro proporcionalmente |
§5 — Perfiles
Perfiles de capacidades
El protocolo se organiza en perfiles. Un binding (MCP, HTTP, A2A) implementa perfiles; el número de tools de un binding puede cambiar sin redefinir el protocolo.
Discoveryestable
12 operaciones en el binding MCP de referencia
Orderingexperimental
4 operaciones en el binding MCP de referencia
Coordinationestable
12 operaciones en el binding MCP de referencia
Deliveryestable
2 operaciones en el binding MCP de referencia
Evidencecandidata
2 operaciones en el binding MCP de referencia
Settlementexperimental
3 operaciones en el binding MCP de referencia
Networkexperimental
5 operaciones en el binding MCP de referencia
§6 — Herramientas
Binding MCP de referencia (40 tools)
15 públicas (sin autenticación) + 25 autenticadas (API key + org ID). Esta lista se genera desde protocol/manifest.yaml y CI la valida contra el código fuente.
Fase 0 — Resolver · 3 tools
resolve.lookup°resolve.search°trust.get_score°
Fase 1 — Descubrimiento · 9 tools
registry.search°registry.get_organization°registry.manifest°registry.list_verticals°registry.list_regions°registry.list_event_types°services.list°scheduling.check_availability°a2a.get_agent_card°
Fase 2 — Entender · 2 tools
service.getcontract.get
Fase 3 — Comprometer · 3 tools
clients.get_or_createscheduling.bookscheduling.confirm
Fase 4 — Ciclo de vida · 4 tools
lifecycle.get_statelifecycle.transitionscheduling.reschedulescheduling.cancel
Fase 5 — Verificar entrega · 3 tools
delivery.checkindelivery.checkoutdelivery.record_evidence
Fase 6 — Cierre · 4 tools
documentation.createpayments.create_salepayments.record_paymentpayments.get_status
Gestión de recursos · 6 tools
resource.listresource.getresource.createresource.updateresource.deleteresource.get_availability
Administración del resolver · 3 tools
resolve.registerresolve.update_endpointtelemetry.heartbeat
Inteligencia de red · 2 tools
market.list_segments°market.get_benchmark°
Documentación · 1 tool
docs.quickstart°
° = pública (sin autenticación). Operaciones especificadas pero no implementadas en el servidor de referencia (service_orders.*, mandates.*): ver /extensions.
§7 — Bindings
Independencia del transporte
Servicialo define la semántica; los bindings definen cómo se expone. La conformidad exige al menos un binding máquina a máquina que implemente los perfiles Core — ninguno en particular. MCP es la vía recomendada para integraciones agénticas, no una condición para usar el protocolo.
HTTPestable
Binding normativo para acceso máquina a máquina: perfil REST (v1.0.0) + OpenAPI 3.1. El protocolo no prescribe rutas: cada implementación elige su superficie. Suficiente por sí solo para la conformidad Core.
HTTP_PROFILE.md →MCPestable
Binding oficial que expone los perfiles como tools y resources MCP: @servicialo/mcp-server (v0.9.13), transportes stdio y streamable-http. Recomendado para agentes; opcional para la conformidad.
npm →A2Aexperimental
Binding oficial de interoperabilidad entre agentes: Agent Cards en /.well-known/agent.json y endpoint JSON-RPC (POST /{orgSlug}/a2a). A2A v0.3. Superficie parcial: descubrimiento e intents de booking.
Intents A2A →Otros bindings son permitidos si implementan la semántica y los requisitos de conformidad. El header wire
X-Servicialo-Version: 1.0 versiona el API del resolver — es independiente de la versión del documento del protocolo (v0.10).§8 — Conformance
Requisitos mínimos
De PROTOCOL.md §16. Cuatro requisitos obligatorios; el resto son extensiones opcionales — incluida la red.
| # | Requisito | Ref. | Obligatorio |
|---|---|---|---|
| 1 | Modelar servicios con las 8 dimensiones | §5 | Sí |
| 2 | Implementar los 6 estados core del ciclo (requested → documented). Los 3 financieros son extensiones opcionales | §6 | Sí |
| 3 | Manejar al menos 3 flujos de excepción | §7 | Sí |
| 4 | Exponer al menos un binding máquina a máquina que implemente los perfiles Core requeridos y declare perfiles y versiones soportados — HTTP, MCP, A2A u otro equivalente. Una implementación puramente HTTP es conforme sin MCP | §13 + HTTP_PROFILE | Sí |
| 5 | Modelar Órdenes de Servicio | §8 | No |
| 6 | Implementar el modelo de agencia delegada | §10 | No |
| 7 | Implementar perfiles de proveedor | §12 | No |
| 8 | Contribuir a la inteligencia de red (la red es opcional) | §14 | No |
Proceso de verificación
Hoy es manual: corres los tests de conformance contra tu backend, abres un PR con el output y el equipo revisa contra esta checklist. Una suite de certificación automatizada y periódica es objetivo del roadmap — no una capacidad actual. Nota: los mandatos delegados están especificados, pero la implementación de referencia no valida sus scopes en el boundary MCP todavía (advisory).
§9 — Principios
Las reglas del protocolo
Siete principios que aplican a cualquier servicio en cualquier vertical (PROTOCOL.md §9).
Principio 01
Todo servicio tiene un ciclo observable
No importa si es un masaje o una auditoría. El protocolo define estados independientes para observar el ciclo completo: entrega, evidencia, aceptación y liquidación — cada dimensión con su propio ciclo de vida, sin un orden total entre ellas.
Principio 02
La entrega debe ser verificable y liquidable
Sin evidencia suficiente, una entrega no puede considerarse acreditada con el nivel de certeza requerido. El protocolo define qué constituye evidencia válida para humanos y agentes IA. Y verificable no basta: la liquidación se concilia con la prueba, no con una declaración.
Principio 03
El pagador no siempre es el cliente
En salud paga la aseguradora. En corporativo la empresa. En educación el apoderado. El protocolo separa explícitamente al cliente del pagador.
Principio 04
Las excepciones son la regla
Inasistencias, cancelaciones, reagendamientos, disputas. Un servicio bien diseñado define qué pasa cuando algo falla.
Principio 05
Un servicio es un producto legible por máquinas
Tiene nombre, precio, duración, requisitos y resultado esperado. Definido así, cualquier agente IA puede descubrirlo, coordinarlo y cerrarlo con la misma confianza que un humano.
Principio 06
El acuerdo es separado de la entrega
La Orden de Servicio define lo acordado. Los servicios atómicos definen lo entregado. Son objetos distintos con ciclos de vida distintos.
Principio 07
El protocolo separa lo acordado, lo entregado, la evidencia y el dinero
Cuatro elementos explícitos, cada uno con su propio ciclo. Una Prueba de Servicio es el expediente que los vincula — no una declaración de que todo salió bien.