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_*.

Related MCP server: SumoSign MCP Server

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

Tools expuestas (49)

Autenticación

Documentos

Firma

Presets de firma

Estudios

Cuenta, webhooks y settings

Próximamente (stub)

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