vidal-helpdesk-mcp

AI-powered helpdesk control plane for the VIDAL ecosystem. Exposes ticket-system through 7 MCP tools via HTTP/SSE, runs an autonomous SLA audit engine on Vercel, and drives hourly compliance reporting through GitHub Actions CI/CD.

Business Value

vidal-helpdesk-mcp acts as an AI-Powered SLA Auditor for the Swiss market. It gives Swiss SMEs and MSPs an operational audit layer that watches SLA drift, flags VIP risk, and generates compliance-ready evidence without requiring a human analyst for every reporting cycle.

Live Demo

Two end-to-end demos recorded against real production data — no mocks, no staging.

Demo 1 · TK-0065 "Error crítico en login (SLA Risk)"

Input Layer — Client submits via mobile form (ES), category Software, priority Alta.

AI Classification — Agent view shows AI Triage at 72% confidence, Active Directory category, SLA on time.

Autonomous Audit — GitHub Actions Remote Audit #8 completes in 8s with zero failures.

Notification Layer — Branded SLA report delivered via Resend: 100% compliance, 4 tickets, Swiss DSG footer.

Demo 2 · TK-0066 "I can not use my DB Software"

Input Layer — Client submits via desktop form (EN), category Software, priority Critical (SLA).

AI Classification — 42% confidence · Urgent sentiment · Smart response generated · ~8h resolution estimate.

Team Communication — Agent internal note + client reply + admin escalation, all with DE/EN/ES translation.

Executive Overview — Real-time dashboard: 5 open tickets, 1 critical, 0 SLA breached, By Category chart.

Urgent Queue — Admin queue detects URGENT / SLA BREACHED — one-click Assign for immediate response.

CI/CD Pipeline — GitHub Actions Remote Audit #9 completes in 10s, fully autonomous.

Notification Layer — 100% SLA compliance across 5 tickets, 3 VIP risks flagged. Swiss DSG certified footer.

Three Pillars

1 · Backend — Supabase PostgreSQL

The data layer. All ticket reads, SLA compliance queries, and write-backs hit Supabase directly through a service-role client (src/lib/supabase.ts) pinned to the isolated helpdesk schema by default. Active statuses tracked: open, in_progress, pending_customer, pending_third_party.

2 · MCP Bridge — Vercel SSE Server

The tool layer. src/vercel-server.ts exposes 7 MCP tools over HTTP/SSE. Any MCP-compatible client (Claude Desktop, remote agent) can connect and operate on tickets programmatically.

3 · Autonomous Audit — GitHub Actions → Vercel → Resend

The automation layer. A GitHub Actions workflow fires every hour, triggers the Vercel audit function, which queries Supabase, computes SLA compliance, and sends a branded HTML report via Resend — no human intervention required.

Full System Flow

flowchart LR
    CLIENT["👤 Client\nmobile / desktop form"]
    TS["🎫 ticket-system\nNext.js 15 + Supabase"]
    AI["🤖 AI Triage\nclassify · sentiment · ETA"]
    AGENT["🧑‍💼 Agent\nqueue · notes · replies"]
    ADMIN["🏢 Admin\ndashboard · SLA alerts"]
    MCP["⚡ MCP Server\n7 tools via HTTP/SSE"]
    GHA["⏱ GitHub Actions\nhourly cron"]
    VF["▲ Vercel\n/api/cron/audit"]
    SB[("🗄 Supabase\nPostgreSQL")]
    RS["✉ Resend\nSLA report email"]

    CLIENT -->|submit| TS
    TS --> AI
    AI --> AGENT
    AGENT --> ADMIN
    TS <-->|read/write| SB
    MCP <-->|7 tools| SB
    GHA -->|POST + Bearer| VF
    VF --> SB
    VF --> RS

CI/CD Flow

flowchart LR
    GHA["⏱ GitHub Actions\ncron · 0 × × × × (hourly)"]
    VF["▲ Vercel\n/api/cron/audit"]
    SB[("🗄 Supabase\nPostgreSQL")]
    RS["✉ Resend\nemail delivery"]
    EM["📬 Executive\nreport"]

    GHA -->|"POST + Bearer token"| VF
    VF -->|"service_role queries\ntickets · SLA · org"| SB
    SB -->|"compliance stats"| VF
    VF -->|"HTML report"| RS
    RS --> EM

Step-by-step:

1. GitHub Actions runs remote-audit.yml on cron (0 * * * *) or workflow_dispatch

2. Sends POST /api/cron/audit with Authorization: Bearer $VIDAL_MCP_AUDIT_SECRET

3. Vercel executes api/cron/audit.ts — validates auth via AUDIT_CRON_SECRET

4. Queries Supabase for active tickets, SLA compliance %, and VIP/high-risk count

5. Renders branded HTML via src/lib/audit-template.ts

6. Sends report through Resend (RESEND_API_KEY)

7. GitHub marks run failed on any non-2xx response

MCP Architecture

flowchart TD
    CD["Claude Desktop"]
    RC["Remote MCP Client"]
    IDX["src/index.ts\nstdio transport"]
    VS["src/vercel-server.ts\nSSE transport"]
    TOOLS["7 Core Tools"]
    SB[("Supabase\nPostgreSQL")]
    ADV["audit_sla\nautonomous-triage-engine"]
    CO["Composio\norchestration layer"]
    GH["GitHub actions"]
    GM["Gmail alerts"]

    CD -->|stdio| IDX
    RC -->|HTTP / SSE| VS
    IDX & VS --> TOOLS
    TOOLS -->|direct client| SB
    IDX --> ADV
    ADV --> CO
    CO --> SB
    CO --> GH
    CO --> GM

The codebase supports two execution modes:

Infrastructure

The infrastructure layer is schema-segregated to satisfy Swiss DSG expectations around isolation, least privilege, and auditability. The SLA audit runtime is pinned to helpdesk, while shared platform primitives stay in public.

Schema Segregation

Version History

Architecture Table

Vercel Routing

Defined in vercel.json:

/api/cron/audit  →  api/cron/audit.ts   (audit endpoint)
/*               →  src/vercel-server.ts  (MCP SSE server)

The audit path is explicit to prevent the MCP catch-all from shadowing it.

Environment Variables

Required for the remote audit path:

SUPABASE_URL=
SUPABASE_SERVICE_ROLE_KEY=
SUPABASE_SCHEMA=helpdesk
MCP_ORGANIZATION_ID=
AUDIT_CRON_SECRET=
RESEND_API_KEY=
RESEND_FROM_EMAIL=

Required for the Composio orchestration layer:

COMPOSIO_API_KEY=
COMPOSIO_USER_ID=
MCP_AGENT_ID=

GitHub Actions secrets required:

VIDAL_MCP_AUDIT_URL      # deployed /api/cron/audit URL
VIDAL_MCP_AUDIT_SECRET   # matches AUDIT_CRON_SECRET

Local Commands

npm install
npm run build      # tsc
npm run dev        # tsx watch src/index.ts (stdio MCP)
npm run start      # node dist/index.js
npm run lint       # tsc --noEmit

Swiss-Market Notes

• Multi-tenant scope is driven by MCP_ORGANIZATION_ID — all queries are org-scoped.

• The audit email reports aggregated SLA indicators only; no ticket body content is included.

• Aligned with the Swiss revDSG / DSG compliance positioning of the wider ticket-system platform.

• Reports carry "Complies with Swiss DSG regulations" footer, generated via Gemini 3 Flash.

Related

• ticket-system — the SaaS helpdesk platform this MCP layer operates on

• Live MCP endpoint: vidal-helpdesk-mcp.vercel.app