SQL Account MCP Server

A hosted remote Model Context Protocol server that lets any MCP-capable AI app (Claude, ChatGPT, Cursor, VS Code, …) read and write a user's SQL Account (Malaysian accounting software) data.

Users install by pasting one URL (https://<mcp>/mcp) and clicking Connect (OAuth login). No Node, no config files, no pasted secrets in AI app settings.

The server never talks to api.sql.my directly. It calls the existing sqlaccount-proxy Edge Function, which owns billing, rate limits, request signing and validation.

How it works

AI app  ──►  MCP server (/mcp)  ──►  sqlaccount-proxy  ──►  api.sql.my
              resource server          (billing, SigV4,
              + OAuth (Supabase Auth)   rate limit, validation)

• OAuth server: Supabase Auth (OAuth 2.1 beta). Issues JWT access tokens via PKCE.

• Resource server: this repo. Validates JWTs against the project JWKS, requires the client_id claim (OAuth-issued tokens only), loads the user's stored credentials from Supabase Vault, and calls the Proxy.

• Credentials: entered once in the portal's "Connect SQL Account" page and stored encrypted in Supabase Vault. This is a change from the n8n node's "never stored" promise; see docs/SECURITY.md.

Related MCP server: QBO-Multicompany-MCP

Endpoints

Configuration

Copy .env.example to .env.local and fill it in. All values are server-only. The server fails fast at startup if any required variable is missing.

Local development

npm install
cp .env.example .env.local   # fill in
npm run dev                  # http://localhost:3000/mcp

npm run lint
npm run typecheck
npm run test
npm run build
npm run gen                  # regenerate src/lib/registry.generated.ts from operations.json
npm run check:contract       # fail if contract/ drifts from CHECKSUMS.txt
npm run check:gen            # fail if the generated registry drifts

Connecting a client

Paste the server URL; OAuth handles the rest.

• Claude / claude.ai custom connector: add a remote MCP server with URL https://<mcp>/mcp, click Connect, approve.

• Cursor (.cursor/mcp.json):

  { "mcpServers": { "sqlaccount": { "url": "https://<mcp>/mcp" } } }

• VS Code (mcp.json):

  { "servers": { "sqlaccount": { "type": "http", "url": "https://<mcp>/mcp" } } }

• ChatGPT connector: add a custom connector with URL https://<mcp>/mcp.

• MCP Inspector: npx @modelcontextprotocol/inspector, transport Streamable HTTP, URL https://<mcp>/mcp.

Tools

Tools are generated from contract/operations.json — never hand-written.

• sqlaccount_list_resources — discovery: every resource, its ops, path_param type, and whether it is verified.

• sqlaccount_<resource>_read — list, get, report get. Read-only.

• sqlaccount_<resource>_write — create, update, delete. Only when ENABLE_WRITE_TOOLS=true; clients should prompt for approval.

Query filters accept the SQL Account wildcards * and ~. Lists paginate at 50 rows per page; set fetch_all_pages: true to page automatically (capped at 500 rows / 10 pages).

Contract

contract/CONTRACT.md and contract/operations.json are copied verbatim from the node/proxy repos and pinned by contract/CHECKSUMS.txt. CI fails on drift. Changing the contract means bumping contract_version in every repo.

Security

See docs/SECURITY.md. Highlights: JWTs verified against JWKS with an ES256/RS256 allowlist; stored credentials read only through a SECURITY DEFINER Vault function with the sub of a verified token; secrets never logged or echoed; the Proxy URL is the only outbound host.

Deployment notes

• Host: Vercel (App Router). Route segment config sets maxDuration = 60 on /mcp, because the Proxy plus SQL Account can take up to 30 s.

• Sessions: mcp-handler reads REDIS_URL (or KV_URL) automatically to keep MCP sessions across serverless instances. Without it, sessions are in-memory per instance. Set REDIS_URL to an Upstash/Vercel KV database for reliable session continuity.

• Well-known paths: MCP_PUBLIC_URL must be the canonical public origin (no trailing slash) so the 401 resource_metadata URL and the metadata resource field match what clients probe. RFC 9728 metadata is served at predictable root paths, which is why this runs on Vercel rather than as a Supabase Edge Function.

• Redis is optional for tool correctness: each request re-resolves credentials and the business logic is stateless; Redis only affects transport session continuity.

License

MIT — see LICENSE.