zyta-sign-mcp

Servidor Model Context Protocol (stdio) que expone tus documentos, firmas y estudios de Zyta Sign a un agente como Claude Desktop, Cursor o Codex CLI — respetando tus permisos exactos.

Instalación rápida (cualquier usuario)

{
  "mcpServers": {
    "zyta": {
      "command": "npx",
      "args": ["-y", "zyta-sign-mcp"],
      "env": {
        "KAIRO_BASE_URL": "https://sign.zyta.app",
        "KAIRO_CLIENT_LABEL": "Cursor"
      }
    }
  }
}

1. Pegá eso en .cursor/mcp.json (Cursor) o claude_desktop_config.json (Claude)
2. Recargá MCP → conectado
3. En el chat: "logueate en zyta" → el agente llama kairo_login → autorizás en /device

No hace falta clonar repos ni rutas locales. Solo Node.js 18+.

Nota: el paquete npm se llama zyta-sign-mcp (el nombre kairo-mcp ya está ocupado en npm por otro proyecto). Las herramientas siguen usando el prefijo kairo_*.

Autenticación (login obligatorio)

Sin sesión autenticada, todas las herramientas fallan — salvo kairo_login y kairo_disconnect. No hay auto-login silencioso por variables de entorno: el token KAIRO_API_TOKEN solo se usa si lo pasás explícitamente a kairo_login({ access_token }) (o como fallback dentro de esa herramienta). Los permisos los determina el usuario del token: el agente no puede hacer más de lo que podés hacer vos en el dashboard.

Device Authorization Flow (recomendado, estilo gh auth login)

El MCP conecta al instante (stdio) sin bloquear en login. Cuando el agente necesita operar, llama a kairo_login:

1. Se abre el navegador en /device?user_code=XXXX-XXXX
2. Autorizás con tu cuenta (o email/contraseña si no tenés sesión web)
3. El agente recibe el token y responde en el chat: "Sesión OK como Juan…"
4. El token queda en ~/.kairo/credentials-*.json (sesiones posteriores se reutilizan)

No hace falta copiar/pegar secretos en mcp.json.

Cursor (recomendado)

1. Levantá la app:

cd kairo-sign
npm run dev          # :3000

2. Configurá .cursor/mcp.json (proyecto o global):

{
  "mcpServers": {
    "zyta": {
      "command": "npx",
      "args": ["-y", "zyta-sign-mcp"],
      "env": {
        "KAIRO_BASE_URL": "http://localhost:3000",
        "KAIRO_CLIENT_LABEL": "Cursor"
      }
    }
  }
}

3. Cursor → Settings → MCP → Reload → kairo conectado (verde)
4. En el chat: "logueate en kairo" o el agente llama kairo_login
5. Autorizás en el browser → mensaje en Cursor (hook) y/o respuesta de kairo_login

Al autorizar en /device, se escribe .cursor/kairo-auth-complete.json y un hook de Cursor muestra en el chat que la sesión quedó lista (al terminar la respuesta del agente o al enviar el próximo mensaje).

Smoke test device flow: cd kairo-sign && npx tsx scripts/smoke-device-auth.ts

Bridge local (misma PC, alternativa al device flow)

Si desarrollás con el dashboard y Cursor en la misma máquina, podés sincronizar la sesión del navegador al MCP sin abrir /device:

1. cd kairo-sign && npm run agent:setup — genera un secreto compartido en .env.local y .cursor/mcp.json (KAIRO_AGENT_BRIDGE_SECRET)
2. Reiniciá npm run dev y recargá el MCP en Cursor
3. Logueate en el dashboard → el front hace POST al puente local (127.0.0.1:9322) y el agente queda autenticado solo

El puente no reemplaza el login obligatorio: solo copia el token cuando ya iniciaste sesión en el browser. En producción remota seguí usando kairo_login (device flow).

Token manual (alternativa)

1. Dashboard → "Acceso para agentes (MCP)" → Crear token
2. En el chat: kairo_login({ access_token: "ztk_..." }) — no lo pongas en mcp.json

Config mínima (sin token manual)

{
  "mcpServers": {
    "zyta": {
      "command": "npx",
      "args": ["-y", "zyta-sign-mcp"],
      "env": {
        "KAIRO_BASE_URL": "https://sign.zyta.app",
        "KAIRO_CLIENT_LABEL": "Cursor laptop"
      }
    }
  }
}

Instalación

npm install -g zyta-sign-mcp
# o on-demand: npx -y zyta-sign-mcp

Claude Desktop

Editá claude_desktop_config.json (Settings → Developer):

{
  "mcpServers": {
    "kairo": {
      "command": "npx",
      "args": ["-y", "zyta-sign-mcp"],
      "env": {
        "KAIRO_BASE_URL": "https://sign.zyta.app"
      }
    }
  }
}

Codex CLI

En ~/.codex/config.toml:

[mcp_servers.kairo]
command = "npx"
args = ["-y", "zyta-sign-mcp"]
env = { KAIRO_BASE_URL = "https://app.zyta.legal" }

Avanzado / legacy: HTTP OAuth en Cursor

Cursor también puede conectarse por URL con OAuth 2.1 (cursor:// redirect). Este flujo es más frágil en Windows (alert del browser, PKCE en Cursor). Preferí stdio + kairo_login arriba.

Si igual querés probarlo:

cd kairo-sign
npm run dev          # :3000
npm run mcp:http     # :3001

{
  "mcpServers": {
    "kairo": {
      "url": "http://localhost:3001/mcp",
      "transport": "http"
    }
  }
}

Smoke test: npx tsx scripts/smoke-cursor-oauth.ts

Flujo típico: subir, firmar y descargar

1. kairo_login si no hay sesión
2. kairo_upload_document({ base64, filename, alias? }) → document.id
3. kairo_get_sign_url({ documentId, mode: "external" }) → url + waitParams
4. Abrís la URL en el browser y firmás con el mouse
5. kairo_wait_for_signature(waitParams) → cuando signed: true, obtenés signature.id
6. kairo_download_signed_pdf({ signatureId }) → PDF firmado en base64
7. kairo_verify_signature({ documentHash }) → verificación por hash

Para firma con tu cuenta (PIN + certificado completo), usá mode: "account" en el paso 3.

Variables de entorno

Variable	Default	Descripción
KAIRO_BASE_URL	http://localhost:3000	URL base de la instancia de Kairo.
KAIRO_API_TOKEN	—	Solo para scripts/CI o kairo_login vía env; no auto-login al arrancar.
KAIRO_CLIENT_LABEL	Agente MCP	Nombre mostrado en la pantalla /device.
KAIRO_AGENT_BRIDGE_SECRET	—	Secreto compartido con el dashboard (bridge local).
KAIRO_AGENT_BRIDGE_PORT	9322	Puerto del puente localhost.
KAIRO_AGENT_BRIDGE	(activo)	0 = no levantar el bridge al arrancar.
BRAVE_PATH	(Windows) ruta a brave.exe	Navegador usado por kairo_login (default: Brave).
KAIRO_TOKEN_CACHE_DIR	~/.kairo	Carpeta donde se guarda el token tras Device Flow.

Tools expuestas (49)

Autenticación

Tool	Qué hace
kairo_login	Inicia sesión (device flow o token manual).
kairo_whoami	Usuario detrás del token.
kairo_disconnect	Borra token cacheado.

Documentos

Tool	Qué hace
kairo_list_documents	Lista documentos visibles.
kairo_get_document	Detalle + firmas.
kairo_download_document	PDF original en base64.
kairo_upload_document	Sube PDF (base64). Requiere scope write.
kairo_upload_documents	Sube hasta 10 PDFs en una llamada.
kairo_update_document	Cambia alias. Requiere scope write.
kairo_delete_document	Elimina documento propio. Requiere scope write.

Firma

Tool	Qué hace
kairo_get_sign_url	URL para firmar + waitParams + share links (WhatsApp/Telegram). Soporta placement e inviteMessage.
kairo_wait_for_signature	Polling hasta firmado.
kairo_sign_workflow	Subir PDF + link externo en un paso.
kairo_request_external_sign	(legacy) Preferí get_sign_url o sign_workflow.
kairo_create_external_bundle	Paquete multi-documento (2–25 PDFs).
kairo_get_external_bundle_status	Estado del paquete.
kairo_wait_for_external_bundle	Polling hasta paquete completo.
kairo_list_external_requests	Pedidos externos de un documento.
kairo_revoke_external_request	Revoca link externo. Requiere scope write.
kairo_download_signed_pdf	PDF estampado en base64.
kairo_get_signature_certificate	Certificado JSON con verifyUrl.
kairo_verify_signature	Verifica por hash del documento.
kairo_verify_document	Verifica subiendo el PDF + signatureId.
kairo_signature_diff	Informe diff PDF (Premium).
kairo_signature_anchor	OpenTimestamps: status / upgrade / .ots
kairo_open_browser	Abre URL de firma en navegador.

Presets de firma

Tool	Qué hace
kairo_list_signature_presets	Biblioteca de firmas guardadas.
kairo_create_signature_preset	Crea preset (PNG base64 obligatorio). Scope write.
kairo_update_signature_preset	Edita preset. Scope write.
kairo_delete_signature_preset	Elimina preset. Scope write.

Estudios

Tool	Qué hace
kairo_list_studios	Estudios donde sos miembro.
kairo_create_studio	Crea estudio (Premium). Scope write.
kairo_get_studio	Detalle con áreas y miembros.
kairo_update_studio	Renombra estudio. Scope write.
kairo_delete_studio	Elimina estudio. Scope write.
kairo_create_studio_area	Crea área. Scope write.
kairo_update_studio_area	Renombra área. Scope write.
kairo_delete_studio_area	Elimina área. Scope write.
kairo_add_studio_member	Agrega miembro por email. Scope write.
kairo_update_studio_member	Cambia rol/área. Scope write.
kairo_remove_studio_member	Quita miembro. Scope write.

Cuenta, webhooks y settings

Tool	Qué hace
kairo_get_plan_quota	Plan, cuota mensual y features.
kairo_get_external_sign_settings	TTL del link externo.
kairo_update_external_sign_settings	Cambia TTL (10m…on_sign). Scope write.
kairo_list_webhooks	Lista webhooks HTTPS.
kairo_create_webhook	Registra webhook. Scope write.
kairo_delete_webhook	Elimina webhook. Scope write.

Próximamente (stub)

Tool	Estado
kairo_create_template	No implementado en backend
kairo_create_sequential_sign	Firma A→B no implementada

Las mutaciones con scope write fallan con 403 si el token es solo lectura.

Modelo de seguridad

• El token está hasheado con HMAC-SHA256 (SIGNING_SECRET) en la base; solo guardamos el prefijo + últimos 4 chars para identificación.
• Cualquier endpoint que el MCP consume usa el mismo getCurrentUserOrToken que el dashboard → no hay "modo admin" oculto.
• Podés revocar un token en cualquier momento desde el dashboard. La revocación es instantánea (no hay TTL de caché).
• Los tokens pueden tener vencimiento opcional (1–365 días).

Desarrollo

npm install
KAIRO_BASE_URL=http://localhost:3000 npm run dev
# o lo inspeccionás con MCP Inspector (login explícito vía kairo_login):
KAIRO_API_TOKEN=ztk_... npm run inspect