@servicialo/mcp-server

MCP server for the Servicialo protocol. Connects AI agents to professional services via any Servicialo-compatible platform.

Protocol version: 0.3 · Package version: 0.5.0

Status: Early-stage protocol with a live reference implementation 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. We're onboarding pilot implementations — get in touch if you're building for professional services.

23 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 23 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 standard 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.5.0 (current)

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

Protocol 0.3 (current)

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

MIT