WoWSQL

npx add-mcp 'https://mcp.wowsql.com/mcp'

WoWSQL MCP (Model Context Protocol)

Servidor HTTP MCP estilo wowsql con OAuth 2.0 authorization code + PKCE en la API de WoWSQL.

Paquetes

Paquete	Descripción
packages/mcp-server-wowsql	@wowsql/mcp-server-wowsql — servidor HTTP MCP, createToolSchemas() para AI SDK

Inicio rápido (proceso MCP autoalojado)

Desde la raíz del repositorio:

cd mcp
npm install
npm run build
npm start

Autenticación (OAuth 2.0 + MCP)

El proceso MCP es un recurso protegido por OAuth (no el servidor de autorización):

1. POST /mcp requiere Authorization: Bearer <access_token> a menos que MCP_ALLOW_UNAUTHENTICATED=true (solo desarrollo).
2. Los tokens faltantes o inválidos reciben 401 con WWW-Authenticate: Bearer ... resource_metadata="<url>" para que los clientes MCP (Cursor, etc.) puedan iniciar OAuth.
3. Validación de tokens llama a tu API: GET {WOWSQL_API_BASE}/api/v1/auth/me con el mismo token Bearer (debe coincidir con el JWT emitido por WoWSQL OAuth o login).
4. Descubrimiento
   • Metadatos del servidor de autorización (API de WoWSQL): GET {WOWSQL_API_BASE}/.well-known/oauth-authorization-server
   • Metadatos del recurso protegido (este host MCP): GET /.well-known/oauth-protected-resource/mcp

Cursor / Electron: los metadatos OAuth se reescriben para que authorization_endpoint, token_endpoint y registration_endpoint apunten a este host MCP (por ejemplo, http://localhost:8787/...). El proceso MCP hace de proxy para esas solicitudes hacia WOWSQL_API_BASE, por lo que el IDE no necesita un fetch directo funcional hacia localhost:8000 para OAuth (que a menudo aparece como fetch failed). Aún necesitas FastAPI ejecutándose en WOWSQL_API_BASE para que el proxy pueda alcanzarlo.

Si MCP_PUBLIC_URL no está definido, PRM y 401 resource_metadata se derivan del Host de cada solicitud (y X-Forwarded-Proto), de modo que http://localhost:8787/mcp y http://127.0.0.1:8787/mcp reciben metadatos coincidentes. Define MCP_PUBLIC_URL cuando el MCP esté detrás de un proxy inverso o necesites un origen fijo único en producción.

Variable	Predeterminado	Propósito
WOWSQL_API_BASE	https://api.wowsql.com	URL base de FastAPI de WoWSQL (sin barra final).
WOWSQL_OAUTH_ISSUER_URL	igual que WOWSQL_API_BASE	issuer anunciado en PRM (authorization_servers).
MCP_PUBLIC_URL	sin definir	Si se define, origen público fijo (sin ruta /mcp) para OAuth PRM + WWW-Authenticate; anula la derivación basada en Host.
MCP_ALLOW_UNAUTHENTICATED	sin definir	Si true, omite la verificación de Bearer (inseguro; solo pruebas locales).
PORT / MCP_PORT	8787	Puerto HTTP de MCP.
MCP_HOST	0.0.0.0	Dirección de enlace.

Opción A — .env / .env.local (recomendada)
Copia packages/mcp-server-wowsql/.env.example a .env o .env.local en esa carpeta. La CLI carga .env, luego .env.local (anula), luego el cwd del proceso .env. Usa .env.local para valores específicos de la máquina (por ejemplo, http://localhost:8000) sin comprometerlos.

cd mcp/packages/mcp-server-wowsql
cp .env.example .env
# edit .env — set WOWSQL_API_BASE to your API
npm run build   # from mcp root: npm run build -w @wowsql/mcp-server-wowsql
npm start

Opción B — shell (sin archivo)

PowerShell:

cd mcp
$env:WOWSQL_API_BASE="http://localhost:8005"
$env:PORT="8787"
npm start

bash / zsh:

cd mcp
export WOWSQL_API_BASE=http://localhost:8005
export PORT=8787
npm start

Endpoints

• MCP (HTTP Streamable): POST http://localhost:8787/mcp — cuerpo JSON-RPC; agrega parámetros de consulta para el alcance. Los clientes MCP (Cursor, etc.) usan esto.
• MCP (navegador): GET http://localhost:8787/mcp devuelve 401 con una página corta de "no autorizado" (sin metadatos públicos). El protocolo es POST JSON-RPC con Authorization: Bearer.
• Salud: GET http://localhost:8787/health

Ejemplo de URL con alcance para clientes:

http://localhost:8787/mcp?project_ref=<uuid-or-slug>&read_only=true&features=database,docs

OAuth (API)

• Metadatos: GET https://api.wowsql.com/.well-known/oauth-authorization-server
• Autorizar (redirigir al panel): GET /api/v1/auth/oauth/mcp/authorize
• Aprobar (usuario con sesión iniciada): POST /api/v1/auth/oauth/mcp/approve
• Token: POST /api/v1/auth/oauth/mcp/token (grant_type=authorization_code o refresh_token)

Interfaz de consentimiento del panel: /mcp/oauth en la aplicación (ver dashboard/app/mcp/oauth/page.tsx).

Desplegar mcp.wowsql.com

1. Ejecuta este servicio Node detrás de TLS (proxy inverso o plataforma de tu elección).
2. Define WOWSQL_API_BASE / WOWSQL_OAUTH_ISSUER_URL a https://api.wowsql.com (no 127.0.0.1:8000/8001). Los cambios blue/green cambian el puerto del host del backend; el nombre de host público siempre sigue la ranura activa a través de NPM.
3. Define MCP_PUBLIC_URL=https://mcp.wowsql.com.
4. Apunta el DNS mcp.wowsql.com al servicio; verificación de salud: GET /health.
5. Asegúrate de que los valores de CORS y OAuth redirect_uri incluyan las devoluciones de llamada de tu cliente MCP (ver oauth_clients seed + env).

EC2 blue/green: ./deploy/ec2-blue-green.sh mcp define esas variables de entorno automáticamente.

Publicación npm

cd mcp/packages/mcp-server-wowsql
npm version patch
npm publish --access public

Requiere un ámbito de organización npm @wowsql (o cambia name en package.json).