WoWSQL MCP (Model Context Protocol)

wowsql-style HTTP MCP with OAuth 2.0 authorization code + PKCE on the WoWSQL API.

Packages

Package	Description
packages/mcp-server-wowsql	@wowsql/mcp-server-wowsql — HTTP MCP server, createToolSchemas() for AI SDK

Quick start (self-hosted MCP process)

From the repo root:

cd mcp
npm install
npm run build
npm start

Authentication (OAuth 2.0 + MCP)

The MCP process is an OAuth protected resource (not the authorization server):

1. POST /mcp requires Authorization: Bearer <access_token> unless MCP_ALLOW_UNAUTHENTICATED=true (dev only).
2. Missing/invalid tokens get 401 with WWW-Authenticate: Bearer ... resource_metadata="<url>" so MCP clients (Cursor, etc.) can start OAuth.
3. Token validation calls your API: GET {WOWSQL_API_BASE}/api/v1/auth/me with the same Bearer token (must match the JWT issued by WoWSQL OAuth or login).
4. Discovery
   • Authorization server metadata (WoWSQL API): GET {WOWSQL_API_BASE}/.well-known/oauth-authorization-server
   • Protected resource metadata (this MCP host): GET /.well-known/oauth-protected-resource/mcp

Cursor / Electron: OAuth metadata is rewritten so authorization_endpoint, token_endpoint, and registration_endpoint point at this MCP host (e.g. http://localhost:8787/...). The MCP process proxies those requests to WOWSQL_API_BASE, so the IDE does not need a working direct fetch to localhost:8000 for OAuth (which often shows up as fetch failed). You still need FastAPI running on WOWSQL_API_BASE so the proxy can reach it.

If MCP_PUBLIC_URL is unset, PRM and 401 resource_metadata are derived from each request’s Host (and X-Forwarded-Proto), so http://localhost:8787/mcp and http://127.0.0.1:8787/mcp each get matching metadata. Set MCP_PUBLIC_URL when the MCP is behind a reverse proxy or you need a single fixed origin in production.

Variable	Default	Purpose
WOWSQL_API_BASE	https://api.wowsql.com	WoWSQL FastAPI base URL (no trailing slash).
WOWSQL_OAUTH_ISSUER_URL	same as WOWSQL_API_BASE	issuer advertised in PRM (authorization_servers).
MCP_PUBLIC_URL	unset	If set, fixed public origin (no /mcp path) for OAuth PRM + WWW-Authenticate; overrides Host-based derivation.
MCP_ALLOW_UNAUTHENTICATED	unset	If true, skips Bearer check (insecure; local testing only).
PORT / MCP_PORT	8787	MCP HTTP port.
MCP_HOST	0.0.0.0	Bind address.

Option A — .env / .env.local (recommended)
Copy packages/mcp-server-wowsql/.env.example to .env or .env.local in that folder. The CLI loads .env, then .env.local (overrides), then the process cwd .env. Use .env.local for machine-specific values (e.g. http://localhost:8000) without committing them.

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

Option B — shell (no file)

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 (Streamable HTTP): POST http://localhost:8787/mcp — JSON-RPC body; append query params for scoping. MCP clients (Cursor, etc.) use this.
• MCP (browser): GET http://localhost:8787/mcp returns 401 with a short “not authorized” page (no public metadata). The protocol is POST JSON-RPC with Authorization: Bearer.
• Health: GET http://localhost:8787/health

Example scoped URL for clients:

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

OAuth (API)

• Metadata: GET https://api.wowsql.com/.well-known/oauth-authorization-server
• Authorize (redirect to dashboard): GET /api/v1/auth/oauth/mcp/authorize
• Approve (logged-in user): POST /api/v1/auth/oauth/mcp/approve
• Token: POST /api/v1/auth/oauth/mcp/token (grant_type=authorization_code or refresh_token)

Dashboard consent UI: /mcp/oauth on the app (see dashboard/app/mcp/oauth/page.tsx).

Deploy mcp.wowsql.com

1. Run this Node service behind TLS (reverse proxy or platform of your choice).
2. Set WOWSQL_API_BASE / WOWSQL_OAUTH_ISSUER_URL to https://api.wowsql.com (not 127.0.0.1:8000/8001). Blue/green flips change the backend host port; the public hostname always follows the active slot via NPM.
3. Set MCP_PUBLIC_URL=https://mcp.wowsql.com.
4. Point DNS mcp.wowsql.com to the service; health check: GET /health.
5. Ensure CORS and OAuth redirect_uri values include your MCP client callbacks (see oauth_clients seed + env).

EC2 blue/green: ./deploy/ec2-blue-green.sh mcp sets those env vars automatically.

npm publish

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

Requires an npm org scope @wowsql (or change name in package.json).