CreaRack-SL

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

Vista limpiaEditar
Runbookactivecreado Fri Jul 10#runbook#security#mcp#operations#cloudflare#github-actions#token-management#workspace

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:

  1. Revierte el deploy de CF Pages:

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

  2. Borras el secret temporal:

    gh secret delete MCP_TOKENS_NEW

  3. Avisa a Edu y revisa logs en rotate-mcp-tokens.yml (GitHub Actions → Workflow runs).

Troubleshooting

SíntomaCausa probableSolución
Workflow rotate-mcp-tokens.yml falla con “CLOUDFLARE_API_TOKEN missing”Secret no está en repoComprueba en Settings → Secrets and variables → Repository secrets
Workflow pasa pero los nuevos tokens devuelven 401El env de CF Pages no ha aplicadoEspera 2-3 min y prueba de nuevo (puede tardar un ciclo de deploy)
OPS server: “permission denied” al escribir /opt/bib-reindex/.tokenUsuario SSH no tiene permisosUsa sudo o ssh como root
Env User BIB_MCP_TOKEN no se aplica en PowerShellSesión vieja, variable no actualizadaCierra 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]]

Referenciado desde

Inicio
Yo