MCP setup guide

Connect Claude to your data

Last updated · 2026-07-17

supalens ships a hosted MCP (Model Context Protocol) server. Connect it once and Claude — on claude.ai, in Claude Code, or in any MCP-compatible client — can query your production database read-only, run the supalens analysis agent, and create dashboards and alerts, straight from 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.
https://mcp.supalens.ai/mcp

Set up in Claude (web & desktop)

  1. Open Settings → Connectors and choose “Add custom connector”.
  2. Paste the connector URL above and save.
  3. Click Connect, sign in to supalens, and approve the consent screen for your workspace.
  4. Ask something: “Show me last week's signups by day.”

Set up in Claude Code

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

Other MCP clients & API keys

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

What Claude can do once connected

  • Query — get_schema and execute_sql (read-only SELECT with row caps) for SQL sources; list_collections, query_documents, and aggregate for Firestore sources.
  • Analyze — ask hands a question to the supalens analysis agent (multi-step NL → SQL → chart); get_analysis polls the result.
  • Dashboards — create_dashboard, add_widget, and register_query persist validated charts to your workspace.
  • Alerts — create_alert (threshold or anomaly with AI root-cause analysis), toggle_alert, delete_alert.
  • Auto-KPI — extract_kpis proposes a validated KPI catalog from your schema (and attached repo); apply_kpis turns it 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

Issue, scope (read / read + write), and revoke tokens in the app: Open supalens → Settings → MCP

supalens · admin@supalens.ai