WoWSQL

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

WoWSQL MCP (Model Context Protocol)

Servidor HTTP MCP estilo wowsql com OAuth 2.0 authorization code + PKCE na API WoWSQL.

Pacotes

Pacote	Descrição
packages/mcp-server-wowsql	@wowsql/mcp-server-wowsql — servidor HTTP MCP, createToolSchemas() para AI SDK

Início rápido (processo MCP auto-hospedado)

A partir da raiz do repositório:

cd mcp
npm install
npm run build
npm start

Autenticação (OAuth 2.0 + MCP)

O processo MCP é um recurso protegido por OAuth (não o servidor de autorização):

1. POST /mcp exige Authorization: Bearer <access_token> a menos que MCP_ALLOW_UNAUTHENTICATED=true (apenas desenvolvimento).
2. Tokens ausentes ou inválidos recebem 401 com WWW-Authenticate: Bearer ... resource_metadata="<url>" para que clientes MCP (Cursor, etc.) possam iniciar OAuth.
3. Validação de token chama sua API: GET {WOWSQL_API_BASE}/api/v1/auth/me com o mesmo token Bearer (deve corresponder ao JWT emitido pelo WoWSQL OAuth ou login).
4. Descoberta
   • Metadados do servidor de autorização (API WoWSQL): GET {WOWSQL_API_BASE}/.well-known/oauth-authorization-server
   • Metadados do recurso protegido (este host MCP): GET /.well-known/oauth-protected-resource/mcp

Cursor / Electron: os metadados OAuth são reescritos para que authorization_endpoint, token_endpoint e registration_endpoint apontem para este host MCP (ex.: http://localhost:8787/...). O processo MCP faz proxy dessas solicitações para WOWSQL_API_BASE, então a IDE não precisa de um fetch direto funcional para localhost:8000 para OAuth (o que frequentemente aparece como fetch failed). Você ainda precisa do FastAPI em execução em WOWSQL_API_BASE para que o proxy possa alcançá-lo.

Se MCP_PUBLIC_URL não estiver definido, PRM e 401 resource_metadata são derivados do Host de cada solicitação (e X-Forwarded-Proto), então http://localhost:8787/mcp e http://127.0.0.1:8787/mcp recebem metadados correspondentes. Defina MCP_PUBLIC_URL quando o MCP estiver atrás de um proxy reverso ou você precisar de uma origem fixa única em produção.

Variável	Padrão	Finalidade
WOWSQL_API_BASE	https://api.wowsql.com	URL base do FastAPI WoWSQL (sem barra final).
WOWSQL_OAUTH_ISSUER_URL	igual a WOWSQL_API_BASE	issuer anunciado no PRM (authorization_servers).
MCP_PUBLIC_URL	não definido	Se definido, origem pública fixa (sem caminho /mcp) para OAuth PRM + WWW-Authenticate; substitui a derivação baseada em Host.
MCP_ALLOW_UNAUTHENTICATED	não definido	Se true, ignora a verificação Bearer (inseguro; apenas testes locais).
PORT / MCP_PORT	8787	Porta HTTP MCP.
MCP_HOST	0.0.0.0	Endereço de bind.

Opção A — .env / .env.local (recomendado)
Copie packages/mcp-server-wowsql/.env.example para .env ou .env.local nessa pasta. A CLI carrega .env, depois .env.local (substitui), e então o cwd do processo .env. Use .env.local para valores específicos da máquina (ex.: http://localhost:8000) sem commitá-los.

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

Opção B — shell (sem arquivo)

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 — corpo JSON-RPC; anexe parâmetros de consulta para escopo. Clientes MCP (Cursor, etc.) usam este.
• MCP (navegador): GET http://localhost:8787/mcp retorna 401 com uma página curta de "não autorizado" (sem metadados públicos). O protocolo é POST JSON-RPC com Authorization: Bearer.
• Health: GET http://localhost:8787/health

Exemplo de URL com escopo para clientes:

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

OAuth (API)

• Metadados: GET https://api.wowsql.com/.well-known/oauth-authorization-server
• Autorizar (redirecionar para dashboard): GET /api/v1/auth/oauth/mcp/authorize
• Aprovar (usuário logado): POST /api/v1/auth/oauth/mcp/approve
• Token: POST /api/v1/auth/oauth/mcp/token (grant_type=authorization_code ou refresh_token)

UI de consentimento do dashboard: /mcp/oauth no aplicativo (veja dashboard/app/mcp/oauth/page.tsx).

Implantar mcp.wowsql.com

1. Execute este serviço Node atrás de TLS (proxy reverso ou plataforma de sua escolha).
2. Defina WOWSQL_API_BASE / WOWSQL_OAUTH_ISSUER_URL para https://api.wowsql.com (não 127.0.0.1:8000/8001). Alternâncias blue/green mudam a porta do host do backend; o hostname público sempre segue o slot ativo via NPM.
3. Defina MCP_PUBLIC_URL=https://mcp.wowsql.com.
4. Aponte o DNS mcp.wowsql.com para o serviço; verificação de saúde: GET /health.
5. Garanta que CORS e valores de redirect_uri OAuth incluam os callbacks do seu cliente MCP (veja seed oauth_clients + env).

EC2 blue/green: ./deploy/ec2-blue-green.sh mcp define essas variáveis de ambiente automaticamente.

Publicação npm

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

Requer um escopo de organização npm @wowsql (ou altere name em package.json).