Stytch-authenticated SQLite MCP

Un servicio MCP remoto deliberadamente pequeño para aprender la forma de una integración SaaS:

• FastMCP ofrece seis herramientas sobre Streamable HTTP.

• Stytch Connected Apps gestiona el descubrimiento OAuth 2.1, el registro dinámico de clientes, PKCE, el inicio de sesión en el navegador, el consentimiento y la emisión de tokens.

• El servicio valida la firma, el emisor, la audiencia, la caducidad y el ámbito openid de cada token de acceso contra el JWKS rotatorio de Stytch.

• Las filas de SQLite se indexan por el sub del token, de modo que cada usuario de Stytch solo ve sus propias notas.

• El servidor limita el acceso a 30 minutos, incluso si un cliente de Stytch se configura accidentalmente con una vida útil de token de acceso más larga.

• El plugin de Claude Code ejecuta un puente mcp-remote fijado, que realiza OAuth y conecta Claude Code con el endpoint MCP remoto.

Arquitectura

Claude Code plugin -> http(s)://MCP/mcp -> validate Stytch JWT -> per-user SQLite CRUD
         |                                      ^
         +-> Stytch discovery -> browser login/consent app -> Stytch token endpoint

La aplicación de navegador es necesaria. Stytch aloja los endpoints de descubrimiento, registro y token, mientras que tu aplicación aloja el componente IdentityProvider utilizado para el inicio de sesión y el consentimiento.

Related MCP server: Supabase MCP Server

1. Configurar Stytch

Crea un proyecto de Consumer Authentication y, a continuación, configura:

1. En Frontend SDK, habilita el SDK y autoriza http://localhost:3000.

2. En Redirect URLs, añade http://localhost:3000/authenticate tanto para el inicio de sesión como para el registro.

3. Habilita Email Magic Links con Login o Create.

4. En Connected Apps, establece la URL de autorización en http://localhost:3000/oauth/authorize.

5. Habilita Dynamic Client Registration. El cliente MCP usa DCR porque su puerto de devolución de llamada puede variar.

6. Establece la caducidad del token de acceso de Connected Apps en 30 minutos donde Stytch lo permita.

El servicio y el plugin solicitan solo openid, porque el servidor MCP solo necesita el identificador estable sub. No necesita datos de perfil ni de correo electrónico.

El servidor rechaza cada token de acceso 30 minutos después del iat de ese token. El plugin usa el puente fijado mcp-remote@0.2.1, que solicita los ámbitos anunciados por el recurso protegido MCP sin añadir offline_access. Por lo tanto, Stytch no emite un token de actualización, y la caducidad devuelve al usuario a la autorización interactiva.

Este puente es intencionado. El OAuth nativo de Claude Code añade automáticamente offline_access cuando el servidor de autorización lo anuncia, lo que permite la actualización silenciosa del token y anula el requisito de inicio de sesión forzado.

Copia .env.example a .env y establece:

• STYTCH_PROJECT_ID: el ID de proyecto project-test-..., utilizado como audiencia JWT.

• STYTCH_DOMAIN: el dominio completo del proyecto que muestra Stytch, como https://...customers.stytch.dev, utilizado como emisor y host de JWKS. No uses aquí el secreto de API ni el token público.

• STYTCH_PUBLIC_TOKEN: el valor seguro para navegador public-token-test-... utilizado por la interfaz de inicio de sesión y consentimiento.

• MCP_BASE_URL: origen visible externamente del servidor MCP, sin /mcp.

Ninguna clave secreta de Stytch pertenece a este proyecto. La verificación JWT solo necesita claves de firma públicas.

Después de guardar la configuración del panel, verifica el descubrimiento de Stytch y las claves de firma:

set -a; source .env; set +a
uv run python scripts/check_stytch.py

No continúes con la prueba de inicio de sesión en el navegador hasta que esto imprima PASS: Stytch authorization metadata and JWKS are ready for MCP OAuth.

2. Ejecutar localmente

uv sync
set -a; source .env; set +a
uv run mcp-auth

En otra terminal:

cd web
npm install
npm run dev

Para una prueba OAuth real, tanto el endpoint MCP como la página de autorización deberían ser normalmente accesibles en URLs HTTPS estables. Un túnel de desarrollo puede publicar los puertos 8000 y 3000. Actualiza MCP_BASE_URL, el entorno autorizado y la URL de redirección del SDK de Frontend de Stytch, la URL de autorización de Connected Apps y SQLITE_NOTES_MCP_URL a esas URLs HTTPS. La configuración simple de localhost es útil durante el desarrollo, pero la producción debe usar HTTPS.

3. Instalar y autenticar el plugin de Claude Code

Desde la raíz del repositorio, registra el marketplace local e instala el plugin para este proyecto:

claude plugin marketplace add "$PWD" --scope project
claude plugin install sqlite-notes@mcp-auth-local --scope project

La URL del servidor local tiene como valor predeterminado http://127.0.0.1:8000/mcp. Para un servidor alojado o tunelizado, establece la URL antes de iniciar Claude Code:

export SQLITE_NOTES_MCP_URL=https://your-mcp-tunnel.example/mcp

A continuación, ejecuta /reload-plugins, abre /mcp y selecciona sqlite-notes. El puente fijado mcp-remote descubre el servidor de autorización de Stytch a través del servidor MCP, se registra, abre el navegador, usa PKCE y regresa con un token de acceso.

Prueba indicaciones como:

• "Crea una nota titulada Lista de la compra con el cuerpo café y naranjas."

• "Lista mis notas."

• "Actualiza la nota 1 para añadir leche."

• "Elimina la nota 1."

Después de 30 minutos, el servidor MCP rechaza el token de acceso actual. Como el puente no solicita offline_access, no puede actualizarse silenciosamente y debe repetir la autorización interactiva.

Pruebas

uv run pytest
cd web && npm run build

Las pruebas automatizadas cubren CRUD y el aislamiento entre usuarios, además del límite de 30 minutos del token de acceso. Un inicio de sesión completo no se puede automatizar sin un proyecto de Stytch configurado y una bandeja de entrada de correo, por lo que el flujo del navegador es una comprobación manual explícita de extremo a extremo.

Notas de producción

SQLite y un único proceso son intencionados para este ejercicio. Para un servicio de pago con múltiples instancias, usa una base de datos gestionada, migraciones, copias de seguridad, HTTPS, registros de auditoría estructurados, límites de tasa y ámbitos de autorización explícitos. Mantén el mismo límite: Stytch autentica al usuario, mientras que tu base de datos y tu servicio deciden qué filas y acciones puede acceder ese usuario.