API y MCP de Scrum Nodriza

Una llave es como una contraseña para herramientas: dice de qué empresa son los datos y qué se puede hacer con ellos. Solo el administrador de la empresa (propietario o gerencia) la crea.

• Entra a Scrum Nodriza y abre Mi empresa → API y MCP (ir ahora).
• Escribe un nombre que te diga para qué es, por ejemplo «Claude de Will».
• Elige Solo leer si la herramienta solo va a consultar, o Leer y escribir si también va a crear, cambiar, priorizar o mover fichas.
• Pulsa Crear llave y cópiala con el botón Copiar llave. Empieza por nsk_ y se muestra una sola vez: si la pierdes, revócala y crea otra.

Quien dirige varias empresas no debería tener que conectar cada una por separado, y por eso hay dos clases de llave. La llave de empresa abre una sola empresa y la crea su administrador. La llave de grupo abre, con una sola conexión, todas las empresas activas de un grupo empresarial —también las que entren al grupo después— y la crean el superadministrador o un administrador del grupo.

• Para crear una llave de grupo, cambia a la vista del grupo (el selector de empresa, arriba, muestra el grupo), abre Mi empresa → API y MCP y verás la sección Llaves del grupo. Desde ahí se crea igual que una de empresa.
• Con una llave de grupo, cada consulta acepta empresa: el nombre, su comienzo (magna, propulsa, nodriza) o el id, sin importar mayúsculas ni tildes. Sin empresa, la respuesta junta todas las empresas y cada elemento trae "empresa": {"id", "nombre"}.
• Para cambiar o mover una ficha basta su código: la empresa sale de la ficha. Como los códigos se repiten entre empresas (cada una tiene su F-001), si el código es ambiguo la respuesta es 409 y pide empresa o el id de la ficha.
• Para crear fichas o sprints con una llave de grupo, empresa es obligatoria; si falta, la respuesta (422) lista las empresas posibles.
• Con una llave de empresa, empresa sobra; si se envía otra empresa, la respuesta es 403.
• Lo que se escribe queda en la bitácora de la empresa tocada, a nombre de la persona de quien creó la llave en esa empresa; si no tiene persona allí, queda sin persona y con constancia de quién creó la llave. La llave de grupo deja de funcionar si quien la creó deja de administrar el grupo.

# Qué empresas abre la llave
curl -H "Authorization: Bearer nsk_…" https://www.nodrizascrum.com/api/v1/empresas

# Sprint en curso de una empresa del grupo
curl -H "Authorization: Bearer nsk_…" "https://www.nodrizascrum.com/api/v1/sprints/actual?empresa=magna"

# Crear una ficha en Propulsa
curl -X POST https://www.nodrizascrum.com/api/v1/fichas \
  -H "Authorization: Bearer nsk_…" -H "Content-Type: application/json" \
  -d '{"empresa": "propulsa", "titulo": "Preparar informe de la convocatoria"}'

En el MCP es lo mismo con palabras: «¿cómo van los sprints de todas las empresas?», «crea en MAGNA una ficha para…». La herramienta listar_empresas le dice al asistente qué nombres puede usar.

Dirección del servidor: https://www.nodrizascrum.com/api/mcp. Transporte HTTP («streamable HTTP»), sin estado, protocolo MCP 2025-06-18.

Claude Code (en la Terminal). Pega este comando cambiando nsk_… por tu llave y pulsa Enter; después escribe claude y pídele, por ejemplo, «¿cómo va el sprint de mi empresa?».

claude mcp add --transport http scrum-nodriza https://www.nodrizascrum.com/api/mcp --header "Authorization: Bearer nsk_…"

claude.ai o Claude Desktop. Los conectores personalizados no dejan escribir cabeceras, así que la llave va dentro de la dirección. En Claude abre Configuración → Conectores → Agregar conector personalizado, ponle de nombre «Scrum Nodriza», pega esta dirección y pulsa Agregar:

https://www.nodrizascrum.com/api/mcp/nsk_…

Esta forma es menos privada: la dirección completa queda en historiales y registros. Usa una llave solo para ese conector y revócala si la dirección se comparte.

ChatGPT y otros clientes MCP (Cursor, VS Code, n8n…). Si el cliente deja poner cabeceras, usa https://www.nodrizascrum.com/api/mcp con Authorization: Bearer nsk_…; si solo pide una dirección y no tiene autenticación, usa la de la llave en la ruta. En ChatGPT se agrega desde los conectores en modo desarrollador. Un archivo de configuración típico:

{
  "mcpServers": {
    "scrum-nodriza": {
      "type": "http",
      "url": "https://www.nodrizascrum.com/api/mcp",
      "headers": { "Authorization": "Bearer nsk_…" }
    }
  }
}

Todas aceptan el argumento opcional empresa, que solo se usa con llaves de grupo (y es obligatorio al crear fichas con ellas). Con una llave de solo lectura el asistente ve únicamente las de consulta. Las de escritura respetan las mismas reglas que la plataforma: puntos Fibonacci, tope del 80 % de capacidad, cupo de mantenimiento y que la aceptación se da en la review.

✎ necesita una llave de lectura y escritura.

Dirección base: https://www.nodrizascrum.com/api/v1. Cada petición lleva la cabecera Authorization: Bearer nsk_…; la empresa sale de la llave, nunca de lo que envíes (con una llave de grupo, eliges entre sus empresas con empresa). La especificación completa, para importar en Postman, n8n o un GPT personalizado, está en /api/v1/openapi.json (OpenAPI 3.1).

Las fichas se nombran por su código (F-012, también 12) o su id; los sprints por número, id, actual o siguiente; las personas por correo, id o nombre exacto.

Leer el sprint en curso:

curl -H "Authorization: Bearer nsk_…" https://www.nodrizascrum.com/api/v1/sprints/actual

Crear una ficha (llave de escritura). Sin sprint nace como idea en el backlog general; con sprint entra priorizada a ese sprint:

curl -X POST https://www.nodrizascrum.com/api/v1/fichas \
  -H "Authorization: Bearer nsk_…" -H "Content-Type: application/json" \
  -d '{"titulo": "Publicar resultados de la convocatoria",
       "historia": "Como coordinador quiero publicar los resultados para que los postulantes los consulten",
       "criterios": ["Publicado en la web", "Correo enviado a postulantes"],
       "puntos": 3, "prioridad": "alta", "responsable": "ana@empresa.com"}'

Moverla en el tablero:

curl -X POST https://www.nodrizascrum.com/api/v1/fichas/F-012/mover \
  -H "Authorization: Bearer nsk_…" -H "Content-Type: application/json" \
  -d '{"estado": "haciendo"}'

Toda respuesta es {"ok": true, "data": …} o {"ok": false, "error": {"codigo", "mensaje"}}, con el código HTTP que corresponde: 400 dato inválido, 401 llave faltante o revocada, 403 llave de solo lectura, 404 no existe en tu empresa, 409 choca con el estado actual, 422 rompe una regla de la plataforma, 429 demasiadas peticiones. Las rutas de la primera versión (/fichas, /sprints, /personas, /desempeno) siguen funcionando y además conservan los campos recurso y datos.

• 120 peticiones por minuto por llave, contadas en la base en ventanas de un minuto. Al pasarlas, la respuesta es 429 con Retry-After: 60.
• Listas: hasta 500 fichas por consulta (100 por defecto) y 100 sprints. Lotes: hasta 30 fichas; priorización: hasta 50.
• Cuerpo de cada petición: máximo 100 KB. Hasta 20 llaves activas por empresa y 20 por grupo. Una llave de grupo cuenta sus peticiones como una sola llave, sin importar cuántas empresas toque.
• La API no cierra sprints, no acepta fichas (eso es de la review) ni toca incentivos o tokens: esas decisiones se toman en la plataforma.

• Guarda la llave como una contraseña. La plataforma solo conserva una huella (sha256): ni nosotros podemos leerla.
• Usa Solo leer siempre que puedas, y una llave distinta por herramienta, para poder revocar una sin afectar las demás.
• Si una llave se filtra, revócala en Mi empresa → API y MCP: deja de funcionar al instante. También deja de funcionar si quien la creó sale de la empresa.
• Todo lo que se escribe con una llave queda en la bitácora de la empresa a nombre de quien la creó, con su origen (API o MCP).
• Antes de pedirle a un asistente que borre o cambie muchas fichas, revisa lo que propone: las herramientas de borrado están marcadas como destructivas para que el asistente pida confirmación.