@servicialo/mcp-server

MCP server for the Servicialo open protocol — the orchestration layer for the AI-agent service economy. Connects AI agents to professional services via any Servicialo-compatible platform.

Protocol version: 0.6 · Package version: 0.6.0

Status: Early-stage protocol with a live reference implementation (Coordinalo) in healthcare (Chile). The protocol spec is stable. The MCP server implements discovery + scheduling + basic lifecycle. Advanced tools (delivery evidence, payments, documentation) are specified but not yet fully wired to backend endpoints. Any platform can implement the protocol as a sovereign node — get in touch if you're building for professional services.

20 tools organized by the 6 lifecycle phases of a service — not by database table.

Two Modes of Operation

Discovery Mode (no configuration)

npx -y @servicialo/mcp-server

No credentials needed. 4 public tools for discovering organizations, services, and availability.

Authenticated Mode

SERVICIALO_API_KEY=your_key SERVICIALO_ORG_ID=your_org npx -y @servicialo/mcp-server

Requires SERVICIALO_API_KEY and SERVICIALO_ORG_ID. Enables all 20 tools across the full service lifecycle.

Claude Desktop Configuration

{
  "mcpServers": {
    "servicialo": {
      "command": "npx",
      "args": ["-y", "@servicialo/mcp-server"],
      "env": {
        "SERVICIALO_API_KEY": "your_api_key",
        "SERVICIALO_ORG_ID": "your_org_id"
      }
    }
  }
}

Omit the env block entirely for discovery-only mode.

Environment Variables

Agent Flow (6 Lifecycle Phases)

1. DESCUBRIR    → registry.*, check_availability, services.list
2. ENTENDER     → service.get, contract.get
3. COMPROMETER  → clients.get_or_create, scheduling.book, scheduling.confirm
4. GESTIONAR    → lifecycle.get_state, lifecycle.transition, reschedule, cancel
5. VERIFICAR    → delivery.checkin, delivery.checkout, delivery.record_evidence
6. CERRAR       → documentation.create, payments.create_sale, record_payment, get_status

A well-designed agent follows this order. Each phase has its tools. The protocol guarantees any agent can complete the full cycle with any compatible implementation.

Phase 1 — Descubrimiento (4 public tools)

Phase 2 — Entender (2 tools)

Phase 3 — Comprometer (3 tools)

Phase 4 — Ciclo de Vida (4 tools)

Phase 5 — Verificar Entrega (3 tools)

Phase 6 — Cerrar (4 tools)

End-to-End Example

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

registry.get_organization({ org_slug: "clinica-kinesia" })
  → list services, providers

scheduling.check_availability({ org_slug: "clinica-kinesia", date_from: "2026-03-01", date_to: "2026-03-07" })
  → available slots

service.get({ service_id: "srv_123" })
  → 8 dimensions: duration 45min, location presencial, billing, etc.

contract.get({ service_id: "srv_123", org_id: "org_456" })
  → evidence: check_in + check_out + clinical_record
  → cancellation: 0% if >24h, 50% if 2-24h, 100% if <2h
  → dispute window: 48 hours

clients.get_or_create({ email: "paciente@mail.com", name: "Maria", last_name: "Lopez", actor: { type: "agent", id: "agent_1" } })
  → client_id: "cli_789"

scheduling.book({ service_id: "srv_123", provider_id: "prov_111", client_id: "cli_789", starts_at: "2026-03-03T10:00:00", actor: { type: "agent", id: "agent_1" } })
  → session_id: "ses_001", state: "requested"

scheduling.confirm({ session_id: "ses_001", actor: { type: "client", id: "cli_789" } })
  → state: "confirmed"

delivery.checkin({ session_id: "ses_001", actor: { type: "provider", id: "prov_111" }, location: { lat: -33.45, lng: -70.66 } })
  → state: "in_progress"

delivery.checkout({ session_id: "ses_001", actor: { type: "provider", id: "prov_111" }, location: { lat: -33.45, lng: -70.66 } })
  → state: "delivered", duration: 42min

delivery.record_evidence({ session_id: "ses_001", evidence_type: "document", data: { type: "clinical_record", signed_by: ["prov_111", "cli_789"] }, actor: { type: "provider", id: "prov_111" } })
  → evidence recorded

documentation.create({ session_id: "ses_001", content: "Sesion de rehabilitacion...", actor: { type: "provider", id: "prov_111" } })
  → state: "documented"

payments.create_sale({ client_id: "cli_789", service_id: "srv_123", provider_id: "prov_111", unit_price: 35000 })
  → sale_id: "sale_001", state: "charged"

lifecycle.transition({ session_id: "ses_001", to_state: "verified", actor: { type: "client", id: "cli_789" } })
  → state: "verified"

Changelog

Package 0.6.0 (current)

Protocol v0.6.0 — Resource as first-class dimension (3.5b).

Package 0.5.0

Consolidated from 38 tools to 20. Tools are now organized by lifecycle phase instead of database entity.

Protocol 0.6 (current)

Resource as a first-class sub-dimension of Location (3.5b). resource_id optional in Location. New exception flow: Resource Conflict (5.7). Scheduler becomes 3-variable: provider ∧ client ∧ resource.

Protocol 0.3

Lifecycle state order changed. Verified moved from position 6 to position 8 (final). Verification is the closure of the cycle — the client needs the full picture (documentation + charge) before confirming.

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

License

Servicialo Protocol is open infrastructure. Licensed under Apache 2.0 — any implementation, commercial or otherwise, is welcome. See LICENSE for details.