supalens
← Supalens home

MCP setup guide

Connect Claude to your data

Last updated · 2026-09-04

supalens ships a hosted MCP (Model Context Protocol) server. Connect it once and Claude — in claude.ai, Claude Code, or any MCP-compatible client — can query your production database read-only, reuse the KPI definitions your team approved, run the supalens analysis agent, and create monitors right from the chat.

Connector URL

One URL for every client. Authentication is OAuth 2.1 (PKCE): on first connect you sign in with your supalens account and approve access for one workspace.
Connector URL
https://mcp.supalens.ai/mcp

Why supalens instead of a raw database MCP?

  • Business rules extracted from code — which status counts as revenue, which accounts are internal tests: read from your repository, not guessed from the schema, and injected into every query.
  • Approved KPI definitions — Claude reuses the definitions your team reviewed and approved, so the same question returns the same number every time.
  • Organization permissions — a token is bound to one workspace and its role (viewer / member) is re-verified on every request. No database password ever lands in a client config.
  • Persistent monitoring — the chat ends, the monitors keep running. An alert created from Claude is evaluated on your plan's interval (every 2 hours on Free, every 10 or 5 minutes on paid plans) and arrives in Slack, Discord, or email with a root-cause investigation.

Set up in Claude (web & desktop)

  1. In Settings → Connectors, choose “Add custom connector”.
  2. Paste the connector URL above and save.
  3. Click Connect, sign in to supalens, and approve the workspace consent screen.
  4. Ask right away: “Compare this month to last month using the approved MRR definition.”

Set up in Claude Code

Add the server from your terminal, then run /mcp inside a session to authenticate:
Set up in Claude Code
claude mcp add --transport http supalens https://mcp.supalens.ai/mcp

Other MCP clients & API keys

Any client that supports streamable HTTP + OAuth connects (Cursor, Windsurf, and the like). For headless or scripted use, mint a long-lived API key in the app (Settings → Developer) and send it as a Bearer token instead of OAuth:
Other MCP clients & API keys
curl https://mcp.supalens.ai/mcp \
  -H "Authorization: Bearer sl_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Prompts that use the operator layer

  • “Compare this month to last month using the approved MRR definition.”
  • “Break down why the refund rate went up last week, by category.”
  • “Create a monitor that pings #founders when daily revenue drops 20% below the 7-day average.”

What Claude can do once connected

  • Query — get_schema and execute_sql (read-only SELECT with a row cap) for SQL sources; list_collections · query_documents · aggregate for Firestore.
  • Analyze — ask hands a question to the supalens analysis agent (multi-step natural language → SQL → chart, with your business context injected); get_analysis polls the result.
  • Dashboards — create_dashboard · add_widget · register_query save validated charts to the workspace.
  • Monitors — create_alert (threshold or anomaly, with AI root-cause investigation), list_alerts, toggle_alert, delete_alert. Monitors created here are evaluated on your plan's interval — every 2 hours on Free, every 10 or 5 minutes on paid plans.
  • Auto-KPI — extract_kpis proposes a verified KPI catalog from the schema (and the connected repo); list_kpis and apply_kpis turn approved ones into a live dashboard.

Security model

  • Read-only by construction: SQL runs through a SELECT-only guard inside a read-only transaction with statement timeouts and row caps — the server has no write path to your database.
  • One token, one workspace: every token is bound to a single organization and can never reach another tenant's data.
  • Write tools (dashboards, alerts, KPIs) additionally require the token's write scope and a member role or above — viewer tokens stay read-only.
  • Tokens are revocable at any time, and the creator's membership is re-verified on every request — a token dies when its creator leaves the workspace.
  • Requests are rate-limited per credential.

Troubleshooting

  • 401 unauthorized — re-connect (OAuth) or check the API key; keys stop working when their creator leaves the workspace.
  • “Multiple data sources” — tell Claude which source to use, or pass dataSourceId.
  • 402 quota exceeded — your plan's monthly question quota is used up; see Settings → Billing.
  • Firestore source rejected by the SQL tools — intentional; ask Claude to use the ask tool or the Firestore document tools instead.

Manage keys & scopes

Mint tokens, set scopes (read / read + write), and revoke them in the app: Open supalens → Settings → Developer
Connect Supabase + GitHub

Streamize Co., Ltd. · CEO JuChan Park · Business Reg. No. 677-87-02793 · admin@supalens.ai