Skip to main content
Glama
WoWSQL MCP

WoWSQL MCP

Official
by WoWSQL

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

Related MCP server: NetSuite MCP Server

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).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP-compatible clients to securely access and query NetSuite data using OAuth 2.0 with PKCE, including SuiteQL, reports, saved searches, and record operations.
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables database querying and modification through an MCP server where each action is gated by human-granted scopes, per-call confirmations for destructive operations, and revocable access.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to sign in with OAuth 2.1 and read a user's WHOOP recovery, sleep, strain, and workout data through read-only tools, while also receiving and forwarding signed WHOOP webhooks to your endpoints.
      MIT