onenote-mcp

Un servidor MCP que expone Microsoft OneNote a través de Microsoft Graph: estructura de cuadernos y secciones, contenido de páginas y escritura a mano renderizada en una imagen que el modelo llamante puede leer.

project-spec.md es el documento de diseño de referencia. Cubre el pipeline de reconstrucción de tinta, las dos capas OAuth independientes, el modelo de despliegue en Cloud Run y la caché de tokens respaldada por Firestore. Léelo antes de cambiar nada aquí.

Requisitos

Node >= 24. @google-cloud/firestore requiere Node >= 22, y Node 24 es el LTS activo actual.

Related MCP server: OneNoteMCP

Inicio rápido

npm ci
npm run build
npm test

Scripts

Los tests viven en test/ y reflejan src/. Se ejecutan directamente contra el código fuente TypeScript usando la eliminación de tipos nativa de Node, por lo que npm test no necesita compilación. Eso restringe el código fuente: sin enum, sin namespace, sin propiedades de parámetros de constructor, y las importaciones de solo tipos deben escribirse import type. Las opciones del compilador erasableSyntaxOnly y verbatimModuleSyntax lo hacen cumplir.

Consulta CLAUDE.md para la estructura de directorios y las convenciones que la acompañan.

Caché de tokens

src/token-cache.ts implementa ICachePlugin de MSAL contra un único documento de Firestore, cuya ruta proviene de FIRESTORE_CACHE_DOC. beforeCacheAccess lee el campo cache del documento y entrega la cadena a MSAL. afterCacheAccess escribe la caché serializada de vuelta dentro de una transacción de Firestore, y solo cuando MSAL informa que la caché ha cambiado. Un documento que no existe se lee como una caché vacía, que es el estado antes de ejecutar npm run bootstrap. Ambos puntos de entrada usan este mismo plugin: el CLI de bootstrap escribe la caché a través de él y el servidor lee a través de él, por lo que hay un solo serializador y ningún segundo formato que mantener sincronizado.

Ese blob es la única copia del token de actualización, por lo que dos cosas lo protegen.

Se rechaza una escritura que vaciaría el documento. MSAL elimina credenciales de su caché en memoria en algunos fallos, y afterCacheAccess se ejecuta dentro del bloque finally de MSAL, por lo que una serialización que ha perdido la cuenta puede llegar a este código mientras la almacenada sigue siendo válida. overwriteWouldEmptyCache lo detiene y registra {"event":"token-cache-write-refused"}. La comprobación de vacío no lee ningún nombre de clave de MSAL — una caché está vacía cuando se analiza como un objeto cuyo cada valor es un contenedor vacío — por lo que no puede invertirse cuando MSAL cambie su formato, y cualquier cosa que no reconozca se deja pasar en lugar de bloquearse.

El blob que cada escritura reemplaza se conserva en un campo previousCache. Una generación, no un historial: la caché se reescribe en cada actualización, y la copia útil es siempre la más reciente buena. Recuperarse de una escritura incorrecta es copiar ese campo sobre cache en la consola de Firestore, lo cual vale la pena porque la alternativa es un inicio de sesión con código de dispositivo. Activa la recuperación en un punto en el tiempo para una segunda capa:

gcloud firestore databases update --enable-pitr

Un fallo de backend no es un fallo de credenciales. Que Firestore sea inalcanzable, o un enlace roles/datastore.user revocado, lanza TokenCacheUnavailableError en lugar de aparecer como el error que produce un token de actualización muerto. Las escrituras se reintentan tres veces antes de eso. Consulta la fila cache-unavailable en la tabla siguiente para ver por qué la distinción vale el código.

npm test cubre solo readCache, la función que decodifica una instantánea de documento. Las dos devoluciones de llamada, la transacción y createFirestoreTokenCachePlugin no tienen prueba automatizada — necesitan un backend de Firestore. Ejercitarlas significa el emulador, que necesita java en PATH y una instalación propia:

sudo apt-get install google-cloud-cli-firestore-emulator

gcloud components install cloud-firestore-emulator no lo instala en una Google Cloud CLI empaquetada con Debian. El administrador de componentes está deshabilitado en esa compilación, y gcloud imprime el comando apt-get anterior en su lugar.

Autenticación de Graph

src/graph-auth.ts convierte la caché de tokens sembrada en un token de acceso de Microsoft Graph. createGraphAuth construye una PublicClientApplication a partir de ONENOTE_CLIENT_ID, ONENOTE_AUTHORITY y el plugin de caché de Firestore, y la mantiene durante la vida del proceso. getAccessToken() lee la cuenta en caché, llama a acquireTokenSilent y devuelve el token. Los ámbitos solicitados son Notes.Read y Notes.ReadWrite, con el nombre completo.

El servidor desplegado nunca inicia sesión de forma interactiva. No tiene forma de solicitar nada a nadie, y los endpoints de OneNote de Graph no admiten autenticación solo de aplicación, por lo que no hay respaldo cuando el token de actualización almacenado muere — un humano vuelve a ejecutar npm run bootstrap. Por lo tanto, cada fallo es un GraphAuthError que lo dice, en lugar de un error MSAL crudo que llegaría al llamante como un 401 desnudo de Graph:

cache-unavailable es la fila que se gana el sueldo. Firestore se lee y escribe dentro de acquireTokenSilent, a través del plugin de caché, por lo que una caída del backend solía llegar como el mismo rechazo que produce un token de actualización muerto — y ese mensaje le dice al operador que vaya a un navegador y reemplace una credencial que está funcionando. GraphAuthError.retryable lleva la distinción y solo esa razón la establece.

Cada uno de estos también escribe una línea en stderr:

{"event":"graph-auth-failure","reason":"silent-failed","documentPath":"tokencache/msal","retryable":"false"}

Esa línea es el punto. De lo contrario, un fallo de herramienta aparece solo dentro de una conversación de Claude, por lo que sin ella nada le dice al operador que el conector ha dejado de funcionar. Consulta Alertas a continuación.

Los mensajes nombran la ruta del documento y el error MSAL subyacente, y deliberadamente no llevan ningún identificador de cuenta: username es el UPN del usuario y homeAccountId incrusta el id. de inquilino, ninguno de los cuales pertenece a un registro.

npm test cubre la lógica de adquisición a través de un cliente falso. createGraphAuth en sí no tiene prueba automatizada: necesita una caché sembrada por un inicio de sesión real con código de dispositivo, y ninguna credencial que pueda sembrar una puede confirmarse. Ejecuta npm run bootstrap y luego el servidor contra el mismo documento para ejercitarlo. Su consumidor es el cliente de estructura de Graph a continuación; nada los conecta todavía a createApp.

Estructura de Graph

src/graph-structure.ts lee el árbol de OneNote: cuadernos, grupos de secciones, secciones y la lista de páginas dentro de una sección. new GraphStructure(auth) toma cualquier cosa con un getAccessToken(), por lo que el servidor le pasa el GraphAuth anterior.

containerKind es notebooks o sectionGroups — los dos nombres de relación de Graph. Ambos tipos de contenedor exponen las mismas relaciones hijas, por lo que los métodos de lista toman el tipo en lugar de existir dos veces.

getExpandedTree() es el barato. Le pide a Graph que expanda las relaciones en lugar de recorrerlas:

GET /me/onenote/notebooks?$select=id,displayName
    &$expand=sections($select=id,displayName),
             sectionGroups($select=id,displayName;$expand=sections($select=id,displayName))

Medido contra una cuenta de 54 cuadernos: una solicitud y 78 KB, frente a 195 solicitudes para getFullTree(), lo que importa porque OneNote permite 400 solicitudes por hora y 5 concurrentes. El $select dentro de cada cláusula de expansión es lo que lleva la respuesta de 441 KB a 78 KB, y el separador dentro de una cláusula que lleva tanto $select como $expand es un punto y coma. Lo que no alcanza es un grupo de secciones anidado dentro de otro grupo de secciones — Graph limita el anidamiento de $expand a dos niveles — por lo que findSectionsByName cubre ese caso en una sola solicitud, filtrando la lista de secciones de toda la cuenta y expandiendo los padres de cada sección.

api-overview.md registra lo que aceptan estos endpoints, incluidos los lugares donde el servicio contradice su propia documentación.

Tres cosas que el recorrido maneja y que una sola llamada a Graph no:

• Anidamiento. Los grupos de secciones son los "grupos de pestañas" de la interfaz de usuario, y contienen más grupos de secciones. getNotebookTree recurre.

• Paginación. Cada llamada de lista sigue @odata.nextLink hasta que deja de aparecer. Graph elige su propio tamaño de página e ignora un $top mayor, por lo que una respuesta nunca es prueba de que una colección esté completa. listPagesInSection se detiene tan pronto como top elementos están en mano, por lo que top es un recuento de resultados en lugar de un tamaño de página.

• La lista de páginas de toda la cuenta nunca se llama. GET /me/onenote/pages falla con el error 20266, "máximo de secciones superado", en una estructura de un cuaderno por año. El listado de páginas siempre está limitado a /me/onenote/sections/{id}/pages, y una prueba escanea src/ en busca de la ruta de toda la cuenta.

Los fallos son GraphRequestError para una respuesta que no sea 2xx — lleva status, statusText y el body de la respuesta, porque el error 20266 solo se distingue de cualquier otro 400 por ese texto — y GraphResponseError para un 2xx cuyo cuerpo no tiene la forma esperada, un listado que no termina, o grupos de secciones anidados más de 20 niveles. Ningún mensaje contiene un nombre de bloc de notas, sección o página.

npm test lo ejecuta todo a través de un fetch falso indexado por URL exacta. Lo que eso no puede comprobar es si Graph acepta esas URLs; las cadenas de consulta provienen del script de reconocimiento validado en el Apéndice A de project-spec.md y se confirman solo ejecutándolo contra el tenant real.

Ink

El endpoint normal de contenido de páginas de Graph elimina la escritura a mano y deja <!-- InkNode is not supported --> detrás, y Graph no puede exportar una página como imagen ni como PDF. Por lo tanto, la escritura a mano se reconstruye a partir de los datos brutos de trazos: GET /me/onenote/pages/{id}/content?includeInkML=true responde multipart/mixed, una parte con el mismo HTML y otra con el InkML. Los trazos se convierten en un SVG y luego en un PNG, que llega al modelo llamante como imagen para que su propia visión lo lea. No interviene ningún servicio de OCR.

Cuatro detalles deciden si esto funciona en absoluto, y los cuatro provienen del script de reconocimiento validado en el Apéndice A de project-spec.md:

• Los espacios de nombres se eliminan. Graph emite inkml:ink, inkml:trace, inkml:traceFormat. fast-xml-parser está configurado con removeNSPrefix: true y cada búsqueda usa el nombre desnudo.

• El orden de canales proviene de <traceFormat>. Los puntos de esta cuenta son X, Y, F, donde F es la presión del lápiz. Leer los dos primeros números de cada punto dibuja la presión como coordenada.

• Las coordenadas son himétricas. px = himetric * 96 / 2540. Ese es el mismo espacio de coordenadas en el que el HTML de la página posiciona el contenido mecanografiado, por lo que la tinta y el contenido mecanografiado podrían registrarse entre sí mediante aritmética.

• Los trazos están en cualquier parte del árbol. Una página puede llevar más de una raíz <ink>, y los elementos <traceGroup> se anidan. Todos se recopilan.

Una página sin tinta se renderiza como null. Esa es la respuesta normal para una página mecanografiada, no un error. Los fallos que sí se lanzan son InkParseError para grupos de trazos anidados más de 50 niveles e InkRenderError para un documento que resvg rechaza; ningún mensaje reproduce el documento, porque las coordenadas de los trazos son la escritura a mano del usuario.

test/fixtures/*.inkml están escritos a mano — unos pocos trazos, orden de canales X/Y/F, unidades himétricas, un archivo con dos raíces <ink> y elementos <traceGroup> anidados. No se puede confirmar ninguna captura de página: la tinta renderizada son notas personales perfectamente legibles.

Endpoint MCP

El servidor habla MCP sobre Streamable HTTP sin estado en POST /mcp. Cada solicitud construye su propio servidor MCP, responde y lo desmonta; nada sobrevive a la siguiente. No hay id de sesión ni SSE — GET /mcp y DELETE /mcp responden 405, y un POST responde con un cuerpo JSON en lugar de abrir un stream. Un stream abierto mantendría viva una instancia de Cloud Run y facturaría por tiempo inactivo.

curl -s -X POST localhost:8080/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# {"result":{"tools":[]},"jsonrpc":"2.0","id":1}

Ambos tipos Accept son requeridos por la especificación Streamable HTTP aunque este servidor nunca transmite. createTools en src/tools.ts es el registro — seis herramientas de navegación (list_notebooks, list_sections, list_pages, search_pages, find_page_by_name, list_pages_by_name), una herramienta de lectura (get_page_content) y tres herramientas de escritura (append_to_page, create_page, update_page_title) — y src/mcp-server.ts es la superficie JSON-RPC que las envuelve.

Una herramienta que lanza una excepción vuelve como resultado de herramienta con isError: true y un mensaje legible — un token de refresco caducado, una página que ya no existe y un documento que resvg rechaza son resultados normales, no fallos de protocolo. Solo una llamada a una herramienta que nunca fue registrada es un error JSON-RPC.

Cada solicitud escribe una línea de log JSON: el verbo HTTP, la ruta, el estado, la duración, el método JSON-RPC y el nombre de la herramienta en un tools/call. Nunca la cadena de consulta, las cabeceras, los argumentos ni el resultado — ver src/logging.ts.

/mcp está cerrado tras un token de portador — ver Tokens de portador en el endpoint MCP. El endpoint de salud permanece abierto.

Descubrimiento OAuth

Claude tiene que encontrar el servidor de autorización antes de poder iniciar un flujo. src/oauth-router.ts monta el mcpAuthRouter del SDK en la raíz de la aplicación — construye sus rutas a partir de la URL del emisor en lugar de desde un punto de montaje, por lo que no puede ir detrás de un prefijo — y sirve cinco rutas, todas ellas sin autenticación por necesidad:

curl -s localhost:8080/.well-known/oauth-authorization-server
curl -s localhost:8080/.well-known/oauth-protected-resource/mcp

Todo en ambos documentos se deriva de MCP_PUBLIC_URL: es el emisor, y el identificador resource es ese valor más /mcp. MCP_PUBLIC_URL se rechaza al inicio si lleva una barra final, para que cada URL construida concatenando una ruta sea correcta; el campo issuer informa entonces la forma normalizada de URL, que para un valor de solo origen es la misma cadena con una barra final añadida. El documento de recurso protegido se sirve solo en la URL con sufijo de ruta — el /.well-known/oauth-protected-resource desnudo es un 404, y también lo es /.well-known/openid-configuration. Claude sondea primero la ruta con sufijo.

scopes_supported lista offline_access, que es lo que hace que Claude pida un token de refresco en lugar de volver a dar consentimiento cada vez que un token de acceso caduca. No hay registration_endpoint: el id de cliente y el secreto están configurados, por lo que el Registro Dinámico de Clientes no tiene nada que hacer. Un cliente está registrado, con tres URI de redirección — https://claude.ai/api/mcp/auth_callback para las superficies alojadas de Claude, y http://localhost/callback más http://127.0.0.1/callback para Claude Code, cuyo puerto se ignora según RFC 8252.

GET /authorize renderiza una página de consentimiento en lugar de redirigir: un botón Aprobar que nombra lo que se concede y el host al que se enviará el código de autorización. Aprobar publica en POST /consent, que acuña un código de un solo uso de 60 segundos y redirige al callback del cliente. Toda la solicitud de autorización cruza esa página en un campo oculto firmado con MCP_TOKEN_SIGNING_KEY, por lo que un reemplazo de instancia a mitad del consentimiento no rompe el flujo y el formulario no se puede editar; un campo que falla la verificación es un 400 sin redirección y sin código acuñado.

Ambas respuestas de consentimiento llevan Cache-Control: no-store, Referrer-Policy: no-referrer — el formulario publica desde la URL /authorize, que tiene state y el desafío PKCE en su cadena de consulta — X-Frame-Options: DENY, y un CSP de default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'. Deliberadamente no hay form-action: los navegadores no se han puesto de acuerdo sobre si se comprueba contra un destino de redirección, y el POST de consentimiento responde con una redirección a claude.ai.

POST /consent tiene un límite de tasa propio — 200 en 15 minutos — porque está montado deliberadamente antes del limitador /authorize del SDK y un formulario renderizado permanece publicable durante diez minutos, por lo que un paso por /authorize produce un campo que se puede reproducir. El límite se sitúa por encima del tope de 100 entradas de códigos pendientes, de modo que la propia expulsión del almacén, cuyo comportamiento está especificado, es lo que un pico encuentra primero.

POST /token emite un token de acceso válido durante una hora y un token de refresco válido durante 30 días. Ambos son un HMAC-SHA256 sobre un payload compacto bajo MCP_TOKEN_SIGNING_KEY y nada más — no se consulta ningún almacén para verificarlos, que es lo que evita que un reemplazo de revisión de Cloud Run fuerce una reconexión. El payload lleva la audiencia, que es MCP_PUBLIC_URL más /mcp, por lo que un token es válido para este endpoint MCP y para ningún otro. Cuánto viven esos tokens, y cómo hacer que un humano apruebe más a menudo, está dos secciones más abajo.

Tokens de portador en el endpoint MCP

Cada solicitud a /mcp necesita Authorization: Bearer <access token>. El requireBearerAuth del SDK se sitúa delante del router MCP en createApp, y verifyAccessToken en src/oauth-provider.ts es lo que llama: la firma HMAC bajo MCP_TOKEN_SIGNING_KEY, el tipo de token, la caducidad y la audiencia. Un token que está correctamente firmado y no caducado pero que lleva el identificador de recurso de otro servidor se rechaza — el SDK no comprueba ninguna audiencia propia, por lo que sin esa comprobación se aceptaría un token acuñado para un servidor MCP diferente por un servidor que comparte esta clave de firma.

Una solicitud sin token, con token caducado o con un token que falla cualquiera de esas comprobaciones es 401 con una cabecera de desafío:

WWW-Authenticate: Bearer error="invalid_token", error_description="…",
                  resource_metadata="https://<MCP_PUBLIC_URL>/.well-known/oauth-protected-resource/mcp"

El parámetro resource_metadata es la parte que importa: es como Claude encuentra el servidor de autorización e inicia el flujo, por lo que un 401 sin él es un callejón sin salida en lugar de un aviso de inicio de sesión. Claude refresca reactivamente ante un 401 y proactivamente unos minutos antes de la caducidad almacenada, por lo que un 401 aquí es un evento ordinario.

El token se lee de la cabecera Authorization y de ningún otro sitio. ?access_token= en la cadena de consulta no se honra — la especificación de autorización MCP lo prohíbe, y src/logging.ts deja la cadena de consulta fuera de la línea de log basándose en eso.

Qué rutas están abiertas es la lista de exenciones, y es más larga que "todo excepto /mcp" porque todo el flujo de autorización tiene que responder a llamantes que aún no tienen token: /healthz y /health, ambos documentos .well-known, /authorize, /consent y /token. Una prueba en test/server.test.ts enumera las rutas que createApp registra realmente y afirma que cada una que no está en esa lista responde 401 sin token, por lo que una ruta añadida después queda cerrada a menos que alguien la abra deliberadamente.

No se requieren scopes. offline_access, el único scope que emite este servidor, trata sobre si se concede un token de refresco más que sobre lo que un llamante puede hacer, y exigirlo respondería 403 para tokens que por lo demás son válidos. Si alguna vez se añade una comprobación de scope, el 403 tiene que llevar WWW-Authenticate: Bearer error="insufficient_scope" — que este middleware hace — porque Claude trata cualquier otro 403 como terminal y no solicita nada.

Duración de tokens y forzar la revalidación

Este servidor está construido para funcionar sin supervisión. La configuración predeterminada refleja eso, y sacrifica cierta capacidad de cortar una credencial filtrada. Lea esto antes de desplegarlo en un lugar que importe, y cambie los números si el intercambio no le conviene.

Qué hacen los valores predeterminados

Claude renueva el access token por su cuenta: de forma proactiva antes de que la hora se haya cumplido, y de forma reactiva ante un 401. Por lo tanto, un humano hace clic en Approve cuando se añade el conector por primera vez, y luego solo si el conector permanece sin uso durante 30 días. Esa es la ventana deslizante: los 30 días limitan cuánto tiempo puede permanecer la conexión inactiva, no cuánto tiempo puede vivir.

Por qué deslizante, y qué supone

Cada token que emite este servidor no tiene estado. Es un payload firmado y nada más: no existe ninguna fila de base de datos, no hay registro de sesión y no hay nada que consultar cuando el token regresa. Eso es lo que hace que la sustitución de una revisión de Cloud Run sea invisible: la nueva instancia verifica un token que emitió la instancia anterior, sin necesidad de compartir estado entre ambas. Un almacén de tokens implicaría una reconexión en cada despliegue.

El precio es que nada se puede revocar de forma individual. No existe un endpoint de revocación porque no hay nada que eliminar. En concreto:

• Un refresh token que se filtra otorga acceso durante hasta 30 días, y cada uso extiende el acceso de su propietario en otros 30. No existe ningún registro en el servidor que invalida y no hay forma de distinguir un refresh token robado de una legítima: ambos son los mismos bytes firmados por la misma clave.

• Deslizar la ventana no es rotación. Cuando una renovación genera un nuevo refresh token, el que reemplaza sigue funcionando hasta la caducidad que lleva estampada en su interior. Una rotación real implica marcar el token anterior como gastado, y eso necesita el almacén de tokens que este diseño no tiene.

• Un access token no se puede cortar dentro de su hora de validez, por la misma razón.

Lo que queda de es una única palanca, y funciona de inmediato: cambia MCP_TOKEN_SIGNING_KEY y vuelve a desplegar. Todos access token, todos los refresh token y cada página de consentimiento abierta se invalidan a la vez, porque la verificación se realiza contra esa clave. La siguiente solicitud de Claude recibe un 401 y el operador hace clic en Approve una vez. Rotar la clave según un calendario es una política razonable por una propia.

La pantalla de consentimiento, para quien encuentre algo, no autenticar a nadie: tiene un único botón y ninguna contraseña. Lo que se por entre un desconocido y sus cuadernos es MCP_OAUTH_CLIENT_SECRET, que POST /token exige; la lista de URL de redireccionamiento permitidas que envía todos los códigos de autorización a claude.ai o ala loopback; y PKCE, que vincula el código al cliente que inició el flujo.

Cómo lograr que un humano apruebe con más frecuencia

Cada una de estas opciones es un cambio en el código fuente, no un valor de configuración. Es decisión deliberada: un operador que corta la ventana de seguridad está cambiando la postura de seguridad del despliegue, y eso pertenece a un commit que alguien pueda leer, no a una variable de entorno que alguien pueda olvidar.

Acortar la ventana de inactividad. En src/oauth-provider.ts:

const REFRESH_TOKEN_TTL_S = 30 * 24 * 60 * 60;   // 30 days
const REFRESH_TOKEN_TTL_S = 7 * 24 * 60 * 60;    // a week

Si un conector lleva ese tiempo sin uso, necesita una clic. Si se usa con regularidad, sigue sin pedirlo nunca: la ventana se sigue deslizando hacia delante. Esto limita cuánto puede sobrevivir un refresh token filtrado después de que el filtro deja de ser utilizado, y lo limita. Nada más.

Detener el deslizamiento de la ventana. Esto es lo que originalmente especificó el issue #22, y limita la vida total de la conexión en lugar de su tiempo de inactividad: un humano aprueba cada 30 días, por muy ocupado que esté el conector. Una línea en exchangeRefreshToken, en: src/oauth-provider.ts:

// Sliding: a new refresh token, 30 days from now.
return issueTokens(client.client_id, requested, mintRefreshToken(client.client_id, granted));

// Fixed: hand back the same token, expiring 30 days after the consent click.
return issueTokens(client.client_id, requested, refreshToken);

Negarse a emitir refresh tokens por completo. Es la configuración más estricta: un humano aprueba cada hora, porque un access token caducado no tiene nada que lo renueve. Son dos ediciones, y ambas son necesarias: el interruptor de metadatos por sí solo no evita que se emita el token.

1. En src/oauth-router.ts, vacía SCOPES_SUPPORTED. Claude solo añade offline_access a una solicitud de autorización cuando los metadatos lo publicitan, y ese es el interruptor que decide si se pide un refresh token.

2. En src/oauth-provider.ts, elimina el campo refresh_token de lo que devuelve issueTokens. Hoy se emite sin que se importen los scopes solicitados.

Espere prever este efecto en uso: Claude envía el navegador de vuelta a la pantalla de consentimiento a mitad de sesión cuando se consuma la hora.

Acortar el access token. ACCESS_TOKEN_TTL_S en src/oauth-provider.ts reduce la ventana en la que un token robado access puede funcionar. Cuesta una solicitud de token por cada caducidad y no requiere la intervención de ningún humano, así que es barato, pero no hace nada con un refresh token filtrado, y un refresh. La credencial que realmente importa.

Keepalive

Los refresh tokens delegados de Microsoft caducan a los aproximadamente 90 días sin ninguna. El token solo avanza cuando se intercambia de hecho, y solo se intercambia cuando llega una llamada de herramienta después de que haya expirado el access token almacenado. Así que un conector que nadie utiliza de uso durante tres meses es un conector needing una persona con un navegador ejecutando npm run bootstrap. En el servidor no hay nada que pueda evitar que si no se ejecuta nada.

POST /keepalive es la solución. Llama a acquireTokenSilent con forceRefresh: true, que se salta el access token almacenado e intercambia el refresh token, con lo que Entra emite un nuevo refresh token con una ventana nueva y src/token-cache.ts lo escribe en Firestore. forceRefresh es la parte importante: sin él, MSAL responde desde su propia caché, no llega ninguna solicitud a Entra y la ventana no mueve.

Cuando MCP_KEEPALIVE_SECRET está establecido en al menos 32 caracteres aleatorios, la ruta está operativa; si se deja sin asignar, la ruta responde 404. Un programador presento el secreto en la cabecera X-Keepalive-Secret, que se compara en tiempo constante antes de hacer el trabajo. Es un secreto compartido, no un bearer token, porque un programador no puede ejecutar el flujo OAuth: no tienes navegador ni lugar donde guardar un refresh token. Y es una variable propia, en lugar del secreto de cliente de Layer-1, para que una credencial que pueda alcanzar toda la superficie MCP no se encuentre también en un trabajo programado.

gcloud scheduler jobs create http onenote-mcp-keepalive \
  --schedule="0 4 * * 1" \
  --time-zone=UTC \
  --uri="https://YOUR-SERVICE-URL/keepalive" \
  --http-method=POST \
  --headers="X-Keepalive-Secret=YOUR-SECRET" \
  --attempt-deadline=60s \
  --max-retry-attempts=3

Un rendimiento semanal es más que suficiente frente a una ventana de 90 días y concede margen para varias ejecuciones fallidas. El trabajo cuesta un viaje de ida y vuelta al endpoint de tokens y una escritura en Firestore.

Lo que esto no protege: una política de frecuencia de inicio de sesión de Access Conditional, una contraseña cambiada, un restablecimiento de MFA o una revocación de la concesión por un administrador. Cualquiera de estas relaciones eliminan esas mata el refresh token, digan lo que digan las programaciones, y ningún cambio de código lo evit. Si el inquilino de Entra es tuyo, debes excepto tu aplicación de las políticas de frecuencia de los inicios; si no es tuyo, considera los 90 días como un límite superior that somebody else can shorten without telling you.

La ruta keepalive tampoco está relacionada con la ventana de 30 días de Layer-1 en Token lifetime más abajo. Ese refresh token reside en el almacén de conectores de Claude, y solo Claude puede presentarlo o recibir su reemplazo, así que nada de lo que aquí se ejecute puede mantenerlo vivo. Perderlo a cuesta una clic en Approve; perder el de Microsoft cuesta un inicio de sesión tipo device with.

Alerting

Dos fallos son invisibles sin una métrica basada en logs, porque ambos se aparecen solo como un mensaje dentro de una conversación de Claude o como una línea que nadie está leyendo:

GXP9:

Luego una política de alerta sobre esa métrica mayor que cero. Una aprobación de consentimiento también vale la pena: POST /consent respondiendo 302 debería ocurre button only cuando se agregue el conector, y el registro de solicitudes ya contiene.

jsonPayload.event="request" jsonPayload.path="/consent" jsonPayload.status=302

Bootstrap

npm run bootstrap es el único inicio de sesión interactivo de Microsoft en el proyecto y se ejecuta en tu máquina, no en Cloud Run. Inicia sesión con el flujo de código de dispositivo y el resultado de la caché de MSAL se escribe en el documento de Firestore que el servidor ejerce.

gcloud auth application-default login

ONENOTE_CLIENT_ID=00000000-0000-0000-0000-000000000000 \
ONENOTE_AUTHORITY=https://login.microsoftonline.com/common \
GOOGLE_CLOUD_PROJECT=your-project \
FIRESTORE_CACHE_DOC=tokencache/msal \
npm run bootstrap

Imprime el mensaje de código de dispositivo de Microsoft, espera a que apruebes en un navegador, luego enumer los notebooks una vez, espera la impresión del contadas de como pruebas que el token funciona. Las líneas finales muestran el proyecto de Firestore y el documento escrito y el inquilino local de la cuenta, para que puedas ver que que iniciado sesión en el directorio correctivo. Esa salida lleva el id de inquilino; mantente away for the issues, pull requests and "workflow logs".

GOOGLE_CLOUD_PROJECT y FIRESTORE_CACHE_DOC son obligatorios aquí, a diferencia del servidor, donde el primero se infiere y el segundo tiene un valor por defecto. El CLI no se debe su uso; an unset value would seed a documento real in the project that your gcloud login points, and todavía show a success. Los valores MCP_OAUTH_* no se leen, así que al ejecutar esto nunca secoloca el secreto de cliente Layer-1 en tu máquina.

Ejecuta de nuevo siempre que aparezca un evento graph-auth- con retryable: "false" en los logs del servidor. El refresh token se rota en cada momento y muere if el servicio permanece inactivo más de los 90 días.

Container

El servicio se despliega en Cloud Run, que ejecuta en linux/amd64. La imagen se compila explícitamente for that platform, so que el binario nativo @resido que se ejecuta en la ruta de ejecución es un Debian node:24-slim` y no debe convertirse en Alpine: el prebuilt de resvg está. está diseñado bajo glibc.

```bash

docker build --platform linux/amd64 -t onenote-mcp .

docker run --rm -p 8080:8080
-e PORT=8080
-e ONENOTE_CLIENT_ID=00000000-0000-0000-0000-000000000000
-e ONENOTE_AUTHORITY=https://login.microsoftonline.com/common
-e MCP_OAUTH_CLIENT_ID=test-client
-e MCP_OAUTH_CLIENT_SECRET=test-secret
-e MCP_TOKEN_SIGNING_KEY=0123456789abcdef0123456789abcdef
-e MCP_PUBLIC_URL=https://onenote-mcp.example.run.app
onenote-mcp

curl -i localhost:8080/health # 200, {"status":"ok",...}

`/healthz` responde con el mismo contenido y es lo que usan los probes de Cloud Run. No lo llames record: el frontend de Google responde a `https://<service>.run.app/healthz` con su propia página 404 y la solicitud nunca llega contenedor; por lo que una verificación de uptime externa tiene que usar `/health`.

Es estas values are solo placeholder tokens that only have enough validity to pass startup validation; they do not auth cualquier cosa. En Cloud Go, `PORT` lo proporciona la plataforma y el resto viene de la retira.

Peor may: if the host port 8080 is occupied, map another one: `-p 8081:8080` with `-e PORT=8080`.

Para probar la imagen:

```bash
RUN_DOCKER_TESTS=1 bash scripts/test/run.sh

Eso construye la imagen, comprueba que el binario glibc de de resvg ha overvivido a la install solo producción y que no se han como dependencias en la de desarrollo, renderiza SVG a PNG dentro del contenedor y value que /healthz responde 200 en el puerto de PORT. Without RUN_DOCKER_TESTS=1 the docker suite is omitted and the rest continues to proceed.

Despliegue

Double-check final: Did I include "XP11" correctly? I used GXP11 even though in one place I wrote GXP.GXP11. Need to correct.

Also "GXP9" appears twice? In the "Alerting" section there is "GXP12" perhaps should be GXP12. In my draft I used GXP9 wrongly. I'll fix to GXP12.

Also "GXP." => GXP11. Need to fix.

Let's go through carefully to write the final version with exact GXP numbers in order: GXP9, GXP10, GXP11, GXP12, GXP13, GXP14, GXP15, GXP16.

There is also "GXP11" after keepalive paragraph, and "GXP12" after alerting table, "GXP13" after next paragraph, "GXP14" after bootstrap paragraph, "GXP15" after container paragraph, "GXP16" after "Para probar la imagen".

Ensure the numbers.

Let's also check "GXP10" in the placeholder after the issue #22.

Now carefully rewrite the final polished translation.

I will now final in a clean complete form, avoiding any glitches.| Token | Duración | Qué lo renueva | | --------------------------- | ---------- | ---------------------------------------------------------- | | Access token | 1 hora | El refresh token, automáticamente | | Refresh token | 30 días | Cada renovación crea un nuevo token con una nueva | 30 días | | Formulario de consentimiento | 10 minutos | Nada; un formulario caducado se rechaza y el flujo se reinicia |

Claude renueva el Access token por su cuenta: proactivamente antes de que se cumpla la hora, y reactivamente ante un 401. Así que una persona hace clic en Approve cuando se añade el conector por primera vez, y después solo si el conector resulta usado durante 30 días. Esa es la ventana deslizante: los 30 días acotan cuánto puede estar la conexión inactiva, no cuánto puede durar su vida.

Por qué deslizable y lo que cuesta

Cada token que este servidor emite no tiene estado. Es un payload firmado y nada más: no hay fila de base de datos, no hay registro de sesión, nada que consultar cuando vuelve. Eso es lo que hace invisible a un reemplazo de una revisión de Cloud Run: la nueva instancia verifica un token que emitió la instancia anterior, con un estado compartido between organization. Un almacén de tokens supondría tener que volver a conectar en cada despliegue.

El coste de esto es que nada se puede revocar individualmente. No existe un endpoint de revocación porque no hay nada que se puede eliminar. En concreto:

• Un refresh token que resulta y se filtra en un lugar "todo el acceso" hasta 30 días, y cada uso permite otra extender, 30 días más al acceso de quien lo posee. No hay un registro en el servidor para invalidar, y no hay forma de distinguir un token de refresco robado de uno legítimo: ambos son los mismos bytes firmados para la misma clave.

• Deslizar la ventana no es una rotación. Cuando una renovación crea un nuevo refresh token, el que reemplaza sigue funcionando hasta la expiración que lleva integrada dentro. Una rotación real implica marcar el token anterior usado, y para eso necesita el almacén de el que este diseño carece.

• Un access token no puede permitirse fuera de su hora, por la misma razón.

Lo que queda es una sola palanca, y funciona inmediatamente: cambiar MCP_TOKEN_SIGNING_KEY y volver a desplegar. Todos los access tokens, todos los refresh tokens y cada página de consentimiento abierta quedan invalidados a la vez, porque todos se verifican contra esa clave. El siguiente solicitud de Claude recibe un 401 y la persona que lo logra hace clic en Approve una vez. Rotar esta clave según una periodicidad se una política razonable por sí misma.

La pantalla de consentimiento, por si sirve de algo, no autentica a nadie: tiene un solo botón y ninguna contraseña. Aquello que se encuentra entre un extraño y tus cuadernos es MCP_OAUTH_CLIENT_SECRET, que POST /token exige; la lista robusta de URLs de redirección que envían todos los authorization codes a claude.ai o al loopback; and PKCE, which binds the handles with the client that initiated the flow.

Cómo logrecer que un humano apruebe más a menudo

Cada una de estas opciones es un cambio en la fuente, ni un valor de configuración. Es algo deliberado: un operador que acorta la ventana está cambiando la postura de seguridad del despliegue, y eso debe quedar en un commit que las personas puedan leer, no a una variable de entorno que se puede olvidadar.

Acortar la ventana de inactividad. En src/oauth-provider.ts:

const REFRESH_TOKEN_TTL_S = 30 * 24 * 60 * 60;   // 30 days
const REFRESH_TOKEN_TTL_S = 7 * 24 * 60 * 60;    // a week

Con tanta inactividad, el conector exige un clic. Si se usa de forma continua, nunca vuelve a pedirlo: la ventana sigue desplazándose hacia delante. Esto limita cuánto sobrevive en un refresh token filtrado después de que dejes de usar la flag que no ha nada más.

Detener el deslizamiento de la ventana. Esto ultimo que el issue #22, y limita la vida total de la conexión en lugar del tiempo de inactividad: una persona aprueba cada 30 días sin importar cuánto lo usa tanto el conector. That is more than in the exchangeRefreshToken.

// Sliding: a new refresh token, 30 days from now.
return issueTokens(client.client_id, requested, mintRefreshToken(client.client_id, granted));

// Fixed: hand back the same token, expiring 30 days after the consent click.
return issueTokens(client.client_id, requested, refreshToken);

Negarse a emitir refresh tokens, por completo. Ajuste más estricto: un humano aprueba cada hora, porque no encontró el access token caducado, a que lo renueve. ¿Qué cambios son dos, y éstas necesarias? data toggle remove table.

1. En src/oauth-router.ts, vacía SCOPES_SUPPORTED: Claude agrega offline_access a una solicitud de autorización solo cuando los metadatos lo anuncian, y esa la llave decide si pedirá un refresh token

2. En src/oauth-provider.ts, quitar el refresh_token de lo que el método de issueTokens devuelve. Lo que se emite hoy, sin importar los scopes que le pidan

Espera que it makes visible in real: Claude manda el navegador de vuelta to consent monkey in active period, cuando se hour termina.

Acortando el access token. ACCESS_TOKEN_TTL_S in src/oauth-provider.ts reduce la ventana en la que un token de acceso fugado funciona. Cuesta una solicitud de token por vencimiento y una solo participación humana en absoluto, así que es barato, pero no tiene nada que ver con un refresh token filtrado, más si esa credencial sale de casa.

Keepalive para token

Los refresh tokens delegados caducan en aproximadamente 90 días sin uso. At the token only moves forward cuando se realmente lo canjea, ¿y? only when there is a new invocation after the current tokens expires. Así que un conector que nadie usa durante 3 meses es un conector que necesita tener a a un a persona delante of a navegador running npm run binary. No hay nada en el servidor que lo pueda prevenirlo si nadie hace without life.

POST /keepalive es la respuesta Failover. Carga acquireTokenSilent con forceRefresh: true, que ignora el token de accessor y newcanjea el refresh, entonces Entra emite a new refresh with silverclea wait forever and src/token-cache.ts write to Firestore the forceRefresh. Keep in this the most.

configure MCP_KEEPALIVE_SECRET_CONFIG with at least 32 random characters and the route is established; if you leave it unset ends, it response 404. House worker exposes "the design" - X-Keepalive- Secret is compared an constant; then we could be dsecret, not like the missing previous sentence.

In GXP helper.

Weekly es big enough against 90-day and so on.

| statusys ... I'll stop, too error-prone. Let me restart.

I realize I made many mistakes in the previous draft. Let me restart confidently with careful translation.

Let's do it stepwise.

TRANSLATION

Claude se renueva por su cuenta: de forma proactiva antes de que se cumpla la hora, y de forma reactiva cuando recibe un 401. Así que un humano hace clic en Approve solo cuando se añade el conector por primera vez, y después solo si el conector lleva 30 días sin usarse. Esa es la ventana deslizante: esos 30 días fijan cuánto tiempo puede estar la conexión inactiva, no cuánto tiempo puede vivir.

Por qué deslizante, y qué implica

Cada token que emite este servidor no tiene estado. Es una carga firmada y nada más: cuando vuelve no hay registro en base de datos, sesión que buscar ni nada parecido. Es justo lo que hace invisible la sustitución de una revisión de Cloud Run: una nueva instancia puede verificar un token que emitió una anterior, sin compartir estado. Un repositorio de tokens implicaría reconectar en cada despliegue.

El coste es que nada puede revocarse de manera individualizada. No existe un endpoint para revocar porque no hay nada que eliminar. En concreto:

• Un refresh token filtrado concede acceso hasta 30 días; cada nuevo uso alarga otros 30 el acceso de su dueño. No hay registro en el servidor que invalidar, ni forma de distinguir un refresh token robado del legítimo: ambos son los mismos bytes firmados con la misma clave.

• Deslizar la ventana no es rotación. Cuando la renovación produce otro refresh token, el anterior sigue en vigor hasta la fecha de caducidad inscrita en su interior. La rotación real marca el token antiguo como gastado, algo que exige el almacén de el que este diseño.

• Tampoco se puede interrumpir un Access antelada de su vida hora de validez, por la misma razón.

Lo que queda es una única palanca, y actúa de inmediato: cambia la clave de firma MCP_TOKEN_SIGNING_KEY y desplo en nuevo. Cada Access token, cada refresh token y cualquier página de consentimiento abierta se invalida en el acto, porque todos se firman val conteúda de esa clave. La siguiente petición de Claude recibe un 401 y el operador hace pedir clic en Approve una sola vez. Rotar esa clave de forma programada es de por sí una política razonable.

The consent screen, and a short a provecho, no autentica a nadie: solo tiene un botón y no hay contraseña. Between a stranger and you there are "your data" the MCP_OAUTH_CLIENT_SECRET value, which requires POST /token, only able to redirects to claude.ai or to loopback; and PKCE, which relacionados with the code client that initiated flow.

Cómo conseguir que un humano apruebe con más frecuencia

Cada una de estas opciones es una modificación del código y no un parámetro configuration. No es casual: el operador que reduce la ventana está cambiando el posture de seguridad del deployment, and for so debe cambios como in commit que alguien pueda revisar y no variable que alguien pueda olvidar.

Acortar la ventana de inactividad. In src/oauth-provider.ts:

Gvepub

Después de tanto tiempo, el conector se tiene que volver a clicar. Si uso normal, no pide nada nunca: la ventana no para de desplazarse resulta ¿This bounds how long a leaked can survive if leak is not being used. Wait, no.

Detener el desplizamiento de la ventana. Esto fue lo que pedía en el issue #22, y pone un tope a toda la vida de la conexión, no the time.

it was inactive: a human reviews the season for 30 days no matter m the whip exercise. in exchangeRefreshToken, under src/oauth-....

const REFRESH_TOKEN_TTL_S = 30 * 24 * 60 * 60;   // 30 days
const REFRESH_TOKEN_TTL_S = 7 * 24 * 60 * 60;    // a week

Negarse a certificar refresh tokens definitivamente. Es la configuración more strict. A human will see every hour because there is no access token valid to renew. Two edits are needed together:

...

Now I got confused. Let me restart and write cleanly entire final answer in a new "scratch" note, with care.

I'll produce final by assembling.

Precise translation with correct structure.

Let’s begin after the table:

Paragraph blob 1:

"Claude refreshes on its own..." etc.

I'll produce these one by one.

Final answer content:

Actually, for "Formulario de consentimiento" use "Formulario de consentimiento". Good.

Then:

Claude refreshes on its own — proactively before the top hour end, and reactively upon a 401. So a human clicks Approve when the connector is first added, and then only if it has been unused for 30 days. That is the sliding window: the 30 days limit how long the connection can stay idle, not how long it can live.

Translation: "Claude renueva los tokens por su cuenta: de forma proactiva antes de que termine la hora, y reactivamente ante un 401. Así pues, una persona hace clic en Approve cuando se añade en conector, y después solo si lleva 30 días sin utilizarse. Esa es la ventana deslizante: el límite de 30 días fija cuánto podrá estar la conexión inactiva, no cuánto podrá vivir."

Then heading:

Por qué es deslizante, y cuál es su custe

Original "Why sliding, and what it costs". that exact heading translation: "Por qué deslizante y cuál es el coste".

Body:

"Cada token que el servidor emite es stateless (sin estado). Es un payload firmado y nada más, sin fila en base de dato, sin registro de sesión, sin nada de buscar available. That is because the Cloud Run is a disposable version invisible: the new instance can verify the token that old one issued, no state reveals the other. A token store would mean reusable reconnecting each deployment."

"El coste es que no se puede revocar nada de forma individual. No existe un endpoint de revocación porque ni hay nothing que delete. En claro:"

List items:

• "Un refresh token que se filtra otorga acceso hasta 30 días por defecto. Y cada uso extiende de nuevo, by otro de 30 days the the access. the? If the server truly does not register, y no hay means which is more, para distinguishing between a stolen and legit, because porque es the exact word bytes signed with the password. "

• "Deslizar la ventana no es rotar. La rotación: when new refresh token is recruited, the old one revokes no, the "expiry" is still worked. Real rotation would mean updates de validación by spent token, and server. Because there is store table not in the design."

• "An Access token ninguna persona not can not cut it "inside their hour" for the same reason."

"Lo que queda es una batea de una puerta direct, y sí funciona. Immediately: modify la MCP."

Oops.

Let's produce a step making sure no malaprop.

Given the token time, I think I can produce an accurate translation without overthinking. Let me now write in final from scratch, meticulously.

I'll write final. Ensure no line using words like "todo el acceso" misformed.

I'll show final| Token | Duración | Qué lo renueva | | --- | ----------- | -------------- | | Access token | 1 hora | El refresh token, automáticamente | | Refresh token | 30 días | Cada renovación genera uno nuevo con una nueva ventana de 30 días | | Consent form | 10 minutos | Nada; un formulario caducado se rechaza y el flujo se inicia de nuevo |

Claude renueva los tokens por sí solo: de forma proactiva antes de que termine la hora, y de forma reactiva ante un 401. Así que un humano hace clic en Approve cuando se añade el conector por primera vez y, luego, solo si el conector completing semelles 30 días de inactividad. Esa es la ventana deslizante: los 30 días limitan cuánto tiempo puede estar la conexión inactiva, no cuánto tiempo puede vivir.

Por qué deslizante, y qué coste tiene

Los tokens que emite este servidor no tienen estado: son una carga útil firmada y nada más, sin fila en la base de datos, sin registro de sesión, sin nada que consultar cada vez que llegan. Eso es lo que hace invisible, la sustitución de una revisión de Cloud Run: la nueva instancia verifica un token que emitió la instancia anterior, sin compartir estado entre ellas. Un almacén de tokens significaría reconectar en cada despliegue.

El coste es que no se deduce revo nar individualmente ningún token. No hay un endpoint de revocación porque no hay nada que revocar. Concretamente:

• Un refresh token que se filtra da acceso durante un máximo de 30 días, y cada uso extiende el acceso de su titular 30 días más. No existe una registro en el servidor que invalidar, así como no es posible distinguir un refresh token robado de uno legítimo: ambos son el mismo byte firmado por la misma clave.

• Deslizar la ventana no es una rotación que consume cuando una renovación genera un refresh token nuevo, al que reemplaza sigue funcionando hasta que caduque la fecha que lleva dentro en su interior. La auténtica rotación consiste en marcar el anterior token como agotado, algo que exige una base que almacene, el almacén que este diseño no tiene.

• No se puede cancelar un access token durante la hora de validez, por la misma razón.

Lo que queda es una única palanca contundente, y funciona de inmediato: cambia MCP_TOKEN_SIGNING_KEY y vuelve a desplegar. Todos los access tokens, todos los refresh tokens y todas las páginas de consentimiento abiertas se invalidan al mismo momento, porque todos se comprueban frente a esa clave. La siguiente petición de Claude recibe un 401401 y el operador solo té que hacer clic en Approve una vez. Rotar la clave con una secuencia programada es, por sí sola, una política razonable.

La pantalla de consentimiento, por si valiera algo, no autentica a nadie: tiene un único botón y ninguna contraseña. Lo que se levanta entre un desconocido y „notebooks“ es el MCP_OAUTH_CLIENT_SECRET que exige POST /token, la lista de permitidas de URI de redirección que envía cada autorización de código de autorización a claude.ai o a loopback, y también PKCE que vincula el código al cliente que inició el flujo.

Cómo conseguir que un humano apruebe con más frecuencia

Cada una de estas opciones es un cambio en el código fuente y no un simple valor de configuración. Es intencionado: un operador que acorta la ventana modifica la situación de seguridad del deployment, y la decisión debe quedar en un commit que cualquiera pueda leer, y no en una variable de entorno que fácilmente se pode olvidar.

Acortar la ventana de inactividad. En src/oauth-provider.ts:

const REFRESH_TOKEN_TTL_S = 30 * 24 * 60 * 60;   // 30 days
const REFRESH_TOKEN_TTL_S = 7 * 24 * 60 * 60;    // a week

Si el conector lleva ese tiempo en desuso, solo hay que hacer un clic. Si se usa con regularidad, sigue sin pedir nunca nada: la ventana de validez no deja de deslizarse hacia adelante. Eso limita cuánto tiempo puede ser usado un refresh token filtrado, después de que se haya dejado de utilizar, y nada.

más que eso.

Detener el deslizamiento de la ventana. Es lo que especificaba originalmente el issue #22, y limita el tiempo: la duración total de la conexión, y no el tiempo de inactividad. Una persona aprueba la conexión cada 30 días, por muy ocupado que esté el conector. Y se consigue con una una sola línea en exchangeRefreshToken, dentro de src/oauth-provider.ts:

// Sliding: a new refresh token, 30 days from now.
return issueTokens(client.client_id, requested, mintRefreshToken(client.client_id, granted));

// Fixed: hand back the same token, expiring 30 days after the consent click.
return issueTokens(client.client_id, requested, refreshToken);

Negarse a emitir refresh tokens rotundamente. Es la configuración más estricta: una persona apruebe cada hora, porque un access token caducado no tiene nada que renovarlo. Hacen falta dos ediciones, ambas necesarias: el conector de metadatos mHSQL.2 por sí solo no no impide que se em

.github/workflows/deploy.yml se ejecuta en cada push a main y en workflow_dispatch. Realiza la comprobación de tipos, ejecuta npm test, compila, construye y publica la imagen del contenedor en Artifact Registry etiquetada con el sha del commit, y despliega esa imagen en Cloud Run. Una comprobación de tipos o un test fallidos detienen la ejecución antes de que se construya una imagen.

No hay ninguna credencial de larga duración en GitHub. El trabajo se autentica mediante Workload Identity Federation: permissions: id-token: write le permite solicitar un token OIDC de GitHub, y google-github-actions/auth@v2 lo intercambia por credenciales de Google de corta duración. scripts/gcp-bootstrap.sh no crea ninguna clave JSON de cuenta de servicio, ni se necesita en ningún sitio. El proveedor solo acepta tokens cuya reclamación repository sea este repositorio.

La imagen se construye en ubuntu-latest, que es linux/amd64 — la plataforma en la que se ejecuta Cloud Run, y para la que está compilado el prebuild de @resvg/resvg-js. Por eso el flujo de trabajo construye la imagen él mismo en lugar de usar gcloud run deploy --source, lo que también implicaría habilitar Cloud Build y conceder los roles asociados.

El despliegue se ejecuta con --max-instances=1 y --allow-unauthenticated, como la cuenta de servicio de ejecución, que tiene roles/datastore.user para la caché de tokens de Firestore. --allow-unauthenticated es lo que permite que Claude llegue al servicio en absoluto; el endpoint MCP está cerrado mediante el token de portador. Véase Tokens de portador en el endpoint MCP.

Qué debe contener el repositorio

scripts/gcp-bootstrap.sh aprovisiona la parte de GCP e imprime los comandos gh variable set para las seis primeras. El flujo de trabajo falla en su primer paso, indicando qué falta, en lugar de desplegar una configuración a medias.

Solo tres de estos son credenciales. El nombre del proveedor WIF y los correos de las cuentas de servicio son identificadores, inútiles para cualquiera que no pueda presentar la identidad OIDC de este repositorio, así que son variables en lugar de secretos.

El despliegue pasa env_vars_update_strategy: overwrite, así que la lista del flujo de trabajo es todo el entorno del servicio en cada revisión. El valor por defecto de la acción es merge, bajo el cual una variable eliminada del flujo de trabajo sobreviviría silenciosamente de la revisión anterior. PORT y GOOGLE_CLOUD_PROJECT están deliberadamente fuera de la lista: Cloud Run proporciona ambos, y rechaza PORT como entrada.

El primer despliegue y MCP_PUBLIC_URL

MCP_PUBLIC_URL es el emisor OAuth y la audiencia de cada token de acceso que emite este servidor, y no existe ningún servicio que tenga una URL hasta que se haya producido el primer despliegue. El flujo de trabajo la resuelve en tres pasos: la variable de repositorio MCP_PUBLIC_URL, luego la URL que Cloud Run ya ha asignado al servicio y, solo cuando no existe ninguna de las dos, https://placeholder.invalid, que sustituye por la URL real inmediatamente después del despliegue. Así, una primera ejecución funciona sin intervención y termina con el valor correcto en su sitio. Deja una advertencia que indica la URL; establece la variable de repositorio con ese valor, porque es la única de las tres fuentes que sobrevive al poner un dominio personalizado delante del servicio.

Cambiar MCP_PUBLIC_URL no invalida nada por sí mismo, pero cada token de acceso ya emitido está vinculado a la audiencia anterior y será rechazado. Claude vuelve a ejecutar el flujo de autorización cuando eso ocurre.

Revertir

La etiqueta de la imagen es el sha del commit, así que una imagen anterior sigue en Artifact Registry:

gcloud run services update-traffic onenote-mcp --region "$GCP_REGION" --to-revisions <revision>=100

Volver a ejecutar el flujo de trabajo desde un commit anterior con workflow_dispatch también funciona, y es el que mantiene el entorno desplegado en sintonía con el archivo de flujo de trabajo de ese commit.

Configuración

Todos los valores provienen de una variable de entorno, validados al arrancar. Una variable ausente o mal formada produce un ConfigError que enumera todo lo que está mal de una vez, y el proceso sale con código 1 sin traza de pila.

FIRESTORE_CACHE_DOC nombra el documento que el plugin de caché de MSAL en src/token-cache.ts lee y escribe. Su valor debe ser una ruta de documento, es decir, un número par de segmentos separados por barras; loadConfig rechaza una ruta de colección al arrancar.

ONENOTE_CLIENT_ID y ONENOTE_AUTHORITY identifican el registro de aplicación de Azure que src/graph-auth.ts presenta a Entra ID. Es un cliente público, así que deliberadamente no hay secreto de cliente de la capa 2; los valores MCP_OAUTH_* que aparecen debajo pertenecen a la capa 1, entre Claude y este servidor, y no están relacionados.

MCP_PUBLIC_URL es la URL a través de la cual Claude llega a este servicio. El emisor OAuth, el identificador resource al que está vinculado un token y la URL del documento de metadatos del recurso protegido se construyen todos a partir de ella. Nada en Cloud Run le dice al proceso en qué URL se le alcanza, y un valor tomado de la cabecera Host sería lo que enviara el llamante, así que se configura. Solo se puede rellenar después de que el primer despliegue haya producido la URL.

npm run bootstrap lee solo ONENOTE_CLIENT_ID, ONENOTE_AUTHORITY, FIRESTORE_CACHE_DOC y GOOGLE_CLOUD_PROJECT — no los valores MCP_OAUTH_* — y exige los dos últimos en lugar de usar valores por defecto. Véase Bootstrap.

Higiene del repositorio

Este repositorio es público. No se deben confirmar contenido de páginas real, tinta renderizada, nombres o IDs de inquilinos de Entra, ni contenidos de documentos de Firestore. .gitignore excluye output/ y los patrones de archivos de la caché de tokens; véase la sección «Higiene del repositorio» de project-spec.md.