WoWSQL MCP server

WoWSQL MCP (Model Context Protocol)

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

Packages

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 unless MCPALLOWUNAUTHENTICATED=true (dev only).
2. Missing/invalid tokens get 401 with WWW-Authenticate: Bearer ... resource_metadata="" so MCP clients (Cursor, etc.) can start OAuth.
3. Token validation calls your API: GET {WOWSQLAPIBASE}/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 {WOWSQLAPIBASE}/.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 authorizationendpoint, tokenendpoint, and registrationendpoint point at this MCP host (e.g. http://localhost:8787/...). The MCP process proxies those requests to WOWSQLAPIBASE, 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 WOWSQLAPI_BASE so the proxy can reach it.

If MCPPUBLICURL is unset, PRM and 401 resourcemetadata 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 MCPPUBLICURL** when the MCP is behind a reverse proxy or you need a single fixed origin in production.

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?projectref=&readonly=true&features=database,docs

OAuth (API)

Shortened. The full README is on GitHub.