WoWSQL

com.wowsqlv1.0.0Updated Oct 5, 2026

Managed Postgres MCP: projects, SQL, docs search, and storage buckets via OAuth.

VerifiedStreamable HTTPWeb executableFiles & Storage Databases

Overview

AI-generated overview

Managed Postgres MCP server that lets an assistant work with WoWSQL projects, run SQL, search docs, and manage storage buckets over OAuth.

What it does: WoWSQL is a remote HTTP MCP endpoint for a managed Postgres platform. According to the description, it exposes tools for projects, SQL execution, documentation search, and storage buckets. The README describes an OAuth 2.0 authorization-code flow with PKCE, where the MCP process acts as an OAuth protected resource and proxies authorization metadata to the WoWSQL API. Requests are JSON-RPC POSTs to /mcp with a Bearer token, and scoped URLs can pin a project and read-only mode.
When to use it: Use it when an assistant needs to inspect or query a WoWSQL-hosted Postgres project, look up platform documentation, or manage storage buckets without leaving the chat client. It fits teams already on WoWSQL who want database work driven through an MCP client such as Cursor.
Requirements: A remote endpoint at or a self-hosted Node.js process built from the @wowsql/mcp-server-wowsql package. OAuth 2.0 authorization-code with PKCE against the WoWSQL API, and a Bearer access token for POST /mcp. Self-hosting needs WOWSQL_API_BASE, optional WOWSQL_OAUTH_ISSUER_URL, MCP_PUBLIC_URL, PORT or MCP_PORT, and MCP_HOST; a running WoWSQL API backend is required for token validation.

Before you install

The server can run SQL and manage storage buckets, so it may read, write, or delete data in a WoWSQL project. Prefer scoped URLs with read_only=true where possible. MCP_ALLOW_UNAUTHENTICATED=true skips the Bearer check and is documented as insecure and for local testing only. OAuth tokens and the API base URL are sensitive; keep .env.local out of version control.

Installation

In SourceWeft

Open WoWSQL in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "mcp": {
      "type": "http",
      "url": "https://mcp.wowsql.com/mcp"
    }
  }
}

README

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:

Authentication (OAuth 2.0 + MCP)

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

POST /mcp requires Authorization: Bearer <access_token> unless MCP_ALLOW_UNAUTHENTICATED=true (dev only).
Missing/invalid tokens get 401 with WWW-Authenticate: Bearer ... resource_metadata="<url>" so MCP clients (Cursor, etc.) can start OAuth.
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).
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.

bash

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

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

Option B — shell (no file)

PowerShell:

bash / zsh:

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`

Run this Node service behind TLS (reverse proxy or platform of your choice).
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.
Set MCP_PUBLIC_URL=https://mcp.wowsql.com.
Point DNS mcp.wowsql.com to the service; health check: GET /health.
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

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

Source: README.md at commit 98f0793

Tools

Tool metadata has not been indexed yet.

Version history

v1.0.0LatestOct 5, 2026