Runbook: Rotación de MCP_TOKENS (workflow automático + manual)

Propósito

Rotar los tokens Bearer del protocolo MCP de forma segura y coordinada. Afecta a:

Cloudflare Pages (env var MCP_TOKENS)
2 repos GH (secret MCP_TOKEN)
OPS server (archivo /opt/bib-reindex/.token)
Env User en 3 PCs (var BIB_MCP_TOKEN)

Duración estimada: 15-20 min (generación) + 5 min/consumidor (distribución).

Requisitos previos

Acceso a repo CreaRackSL-workspace (main branch)
gh CLI autenticado con scope repo:admin + workflow
Acceso a Cloudflare API (secret CLOUDFLARE_API_TOKEN en repo)
Acceso a OPS server (SSH a 100.96.245.233, root o sudo)
Acceso a Bitwarden / bóveda de tokens (guardar nuevos)
Coordinación con Edu (autor de MCP_TOKENS)

Procedimiento

Paso 1: Generar tokens nuevos

Ejecuta en Windows (workspace repo, carpeta scripts/):

cd scripts
.\generate-mcp-tokens.ps1

Salida esperada:

Edu  ->  abc123def456...  (40 chars)
Dani ->  xyz789uvw012...  (40 chars)
Txell-> mno345pqr678...  (40 chars)
CI   ->  stu901vwx234...  (40 chars)

Copia estos valores a Bitwarden bajo MCP_TOKENS_NEW (no dejes en pantalla)
Compón la string: Edu:abc123...,Dani:xyz789...,Txell:mno345...,CI:stu901...

Paso 2: Configurar secret temporal en GH

gh secret set MCP_TOKENS_NEW -R CreaRackSL/CreaRackSL-workspace

Pide input interactivo: pega la string Nombre:token,... (se encripta en GH, no aparece en logs).

Paso 3: Ejecutar workflow de rotación

gh workflow run rotate-mcp-tokens.yml -R CreaRackSL/CreaRackSL-workspace

Espera a que termine (~30 seg):

gh run watch -R CreaRackSL/CreaRackSL-workspace

Si falla: verifica CLOUDFLARE_API_TOKEN en GH secrets (scope: Account → Cloudflare Pages → Edit)
Si es éxito: ✅ MCP_TOKENS está actualizado en CF Pages env var

Paso 4: Deployan los nuevos tokens (CF Pages)

gh workflow run cf-pages-deploy.yml -R CreaRackSL/CreaRackSL-workspace

⚠️ Importante: el env var se aplica en el SIGUIENTE deploy, no inmediatamente. Espera a que termine el workflow (~1-2 min).

Paso 5: Distribuir a consumidores

GH secret MCP_TOKEN (token CI):

# Workspace
gh secret set MCP_TOKEN -R CreaRackSL/CreaRackSL-workspace <<< "stu901vwx234..."

# CreaRack-Pro
gh secret set MCP_TOKEN -R CreaRackSL/CreaRack-Pro <<< "stu901vwx234..."

OPS server (SSH):

ssh root@100.96.245.233 "echo 'stu901vwx234...' > /opt/bib-reindex/.token && chmod 600 /opt/bib-reindex/.token"

Env User (Windows, cada persona su token):

Edu: setx BIB_MCP_TOKEN "abc123def456..." (cierra sesión y reabre)
Dani: Edu le entrega el suyo en persona + tarea en Gestor (copiar a env User)
Txell: Idem

Paso 6: Verificar

Token nuevo acepta requests:

curl -H "Authorization: Bearer abc123def456..." https://crearacksl-workspace.pages.dev/api/mcp/tools/list
# → 200 OK

Token viejo rechaza (401):

curl -H "Authorization: Bearer <TOKEN_VIEJO>" https://crearacksl-workspace.pages.dev/api/mcp/tools/list
# → 401 Unauthorized

GH Actions/crons funcionan:

Lanza manualmente gh workflow run biblioteca-lint.yml
Revisa logs: debe autenticarse con token CI sin errores 401

Paso 7: Limpiar

Borra el secret temporal:

gh secret delete MCP_TOKENS_NEW -R CreaRackSL/CreaRackSL-workspace

Actualiza el inventario de secretos wiki (fecha + quién rotó + razón).

Rollback (si algo falla)

Si los tokens nuevos no funcionan antes de pasar a producción:

Revierte el deploy de CF Pages:

gh workflow run cf-pages-deploy.yml --ref <SHA_ANTERIOR>

Borras el secret temporal:
```
gh secret delete MCP_TOKENS_NEW
```
Avisa a Edu y revisa logs en rotate-mcp-tokens.yml (GitHub Actions → Workflow runs).

Troubleshooting

Síntoma	Causa probable	Solución
Workflow `rotate-mcp-tokens.yml` falla con “CLOUDFLARE_API_TOKEN missing”	Secret no está en repo	Comprueba en `Settings → Secrets and variables → Repository secrets`
Workflow pasa pero los nuevos tokens devuelven 401	El env de CF Pages no ha aplicado	Espera 2-3 min y prueba de nuevo (puede tardar un ciclo de deploy)
OPS server: “permission denied” al escribir `/opt/bib-reindex/.token`	Usuario SSH no tiene permisos	Usa `sudo` o ssh como root
Env User `BIB_MCP_TOKEN` no se aplica en PowerShell	Sesión vieja, variable no actualizada	Cierra PowerShell completamente y reabre

Auditoría + Historial

Cada rotación debe registrarse en [[crearack-tech—guides—inventario-de-secretos]] (tabla “Rotaciones”):

Fecha
Secret rotado
Razón (higiene, sospecha, auditoría)
Quién ejecutó

Véase también

[[decision—20260710—mcp-tokens-rotacion-p1a-ejecutada]]
[[crearack-tech—guides—secret-rotation-playbook]]
[[crearack-tech—guides—inventario-de-secretos]]
[[feature—mcp—maintenance-agent-token]]
[[concept—general—como-se-autentica-el-endpoint-mcp-del-workspace-ap]]