@freeticket/mcp

Servidor MCP (Model Context Protocol) oficial de FreeTicket. Expone el dominio B2B —eventos, fechas, ventas, tickets, membresías, venues, staff, informes— como tools a cualquier cliente MCP (Claude Code, Claude Desktop, etc.).

Mismo contrato y misma sesión que el CLI ft: si ya hiciste ft login, el MCP queda autenticado sin configurar nada (lee ~/.freeticket/config.json).

Uso (Claude Code / Claude Desktop)

{
  "mcpServers": {
    "freeticket": {
      "command": "npx",
      "args": ["-y", "@freeticket/mcp"]
      // Sin env: usa la sesión de `ft login`. Para CI/headless:
      // "env": { "FT_API_KEY": "ft_live_...", "FT_WORKSPACE_ID": "ws_..." }
    }
  }
}

Config: env > ~/.freeticket/config.json > default. Variables: FT_API_URL (base, sin /api/v1), FT_API_KEY, FT_WORKSPACE_ID, FT_ADMIN_SESSION (habilita los tools admin_* del contrato superadmin /api/admin).

Related MCP server: API to MCP

Uso remoto por URL (HTTP)

Además del stdio, el server corre por Streamable HTTP para agregarlo como connector por URL (claude.ai, Claude Code remoto, curl) sin instalar nada local:

freeticket-mcp-http          # escucha en :3333 (PORT para cambiarlo)

Es stateless: cada request trae sus credenciales y el server arma clientes aislados por sesión (nunca lee el disco), así un mismo proceso sirve a varios workspaces sin cruzar sesiones. Endpoints:

Conectar en claude.ai (Add custom connector)

El server trae un authorization server OAuth 2.1 embebido — es lo único que claude.ai sabe hablar (no puede mandar API keys ni headers custom). Pasos:

1. claude.ai → Settings → Connectors → Add custom connector.

2. Remote MCP server URL: https://<tu-deploy>/mcp. Client ID/Secret: vacíos (usa dynamic client registration, RFC 7591).

3. Al conectar se abre el consentimiento: botón "Continuar con FreeTicket" → inicias sesión en free-admin con tu cuenta de siempre y apruebas (device flow RFC 8628, el mismo backend que ft login). Sin keys que pegar; si tienes varios workspaces, eliges cuál conectar. Bajo "Opciones avanzadas" queda el form manual (API key para CI, cookie superadmin para los admin_*).

4. Las credenciales se sellan (AES-256-GCM, MCP_TOKEN_SECRET) dentro del token emitido — el server no persiste nada: sin base de datos, multi-tenant seguro.

Flujo estándar completo: discovery RFC 9728/8414 → /register → /authorize (PKCE S256) → /token (con refresh). FT_OAUTH_ISSUER delega todo a un AS externo (p. ej. cuando free-admin publique el suyo).

Auth directa (curl, clientes propios)

curl -X POST http://localhost:3333/mcp \
  -H 'authorization: Bearer ft_live_...' \      # API key cruda
  -H 'x-workspace-id: ws_...' \                 # opcional
  -H 'x-admin-session: <cookie>' \              # opcional — habilita admin_*
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Deploy en Vercel

El repo ya trae vercel.json + api/server.ts (misma lógica que el binario, como Vercel Function):

vercel                                        # preview
vercel env add MCP_TOKEN_SECRET production    # openssl rand -hex 32
vercel --prod

Env en Vercel: MCP_TOKEN_SECRET (requerido — sin él los tokens mueren en cada cold start), FT_API_URL (opcional, default producción), MCP_PUBLIC_URL (opcional — se deriva del Host). Connector URL resultante: https://<proyecto>.vercel.app/mcp.

Tools

B2B /api/v1 (un tool = una operación del contrato). Los writes destructivos (*_delete, *_refund, *_cancel) llevan destructiveHint y piden confirmación.

Pendientes por hueco de contrato (el spec no declara requestBody; no se inventan — ver CONTRACT-GAPS.md): event_dates_create/update, ticket_types_update, plans_update, venues_update.

Público B2C /api/public (sin credenciales — el agente de un comprador):

Los public_* se registran siempre (anónimos). El agente nunca toca el pago: public_orders_create devuelve el link de Mercado Pago para que el humano pague. Alcance del checkout: admisión general (no numerado / no members-only).

Superadmin /api/admin (solo con FT_ADMIN_SESSION):

Desarrollo

pnpm install
pnpm generate     # regenera src/client/ y src/admin-client/ desde los specs
pnpm dev          # corre el server vía stdio
pnpm typecheck && pnpm test

Los contratos openapi.json (/api/v1) y admin-openapi.json (/api/admin) los sirve free-admin y son la única fuente de verdad — linajes semver separados. Para propagar un cambio del backend, usá el agente contract-sync del paraguas ai-native.

MIT.