For Developers · Model Context Protocol

Give every AI agent the same trusted data brain.

Supper connects Claude, MCP tools, and internal agents to your governed semantic layer, so every answer, workflow, and automated report uses the right data, definitions, and permissions.

What it is

A production MCP server, 4 tools

Auth

OAuth, or a service token

First query

Minutes to your first query

Available on

Scale & Enterprise plans

§ 00

The Problem

Your agents are only as good as the data layer they call.

Give 100 agents raw access to your warehouse and you get 100 versions of revenue, AUM, customer status, and risk. Every agent invents its own logic. Nobody's numbers agree.

The instinct is to build more APIs. More unique SQL views. More custom connectors for every new agent and every new shape of question. That doesn't scale. It just moves the ticket queue from your data team to your platform team.

Supper is the unified semantic data layer that equips your agents with fast, accurate data for every use case, on demand.

§ 01

How It Works

One governed layer for every agentic workflow.

Ask · govern · answer

Any MCP caller

Claude

Internal agent

Headless workflow

Supper

Governed semantic layer

business logic metric definitions permissions · validation

Your live systems

BigQuery

Segment

Salesforce

Internal APIs

01 · Ask

Ask

Claude, an internal agent, or any MCP-compatible tool sends a question or task to Supper. No new API to build. No GraphQL to extend.

02 · Govern

Govern

Supper applies your semantic model: business logic, metric definitions, and permissions, down to the column, term, category, and skill level. The query is validated before it runs.

03 · Answer

Answer

Supper queries your live systems and returns a verified answer with full reasoning and an audit trail. Same answer, same definitions, every agent, every time.

One governed layer. Every agent draws on the same source of truth.

§ 02

The request lifecycle

How your agents use Supper.

A call to ask runs the full Supper pipeline: parse the question, map it to the right tables, apply your business definitions, validate the generated query, execute against live data, return an answer with its working attached. Same six steps whether the caller is a person in Supper's chat or a line of code in your backend.

→ No "dev mode" that skips validation. Every call is checked before it touches your warehouse.
→ Simple questions resolve in ~10–20s; complex multi-table joins can take 60–120s.
→ Long-running queries return a processing status, so poll, don't block.
→ Every call is attributed and logged, same as any other Supper query.

backend session · calling the Supper MCP

# 1. ask a question in plain language ask("top 5 accounts by open pipeline this quarter") → {"status": "processing", "query_id": "q_8f21..."} # 2. poll instead of blocking on a slow join get_pipeline_status("q_8f21...") → {"status": "complete"} # 3. pull the structured rows behind the answer get_answer_rows("q_8f21...") → [{"account": "Acme Co", "pipeline_usd": 184000}, ...]

Fig. 01 · A question, resolved in three calls, no schema required.

§ 03

Tool surface · auth · scale

Building blocks.

How to implement Supper's MCP toolkit.

Everything Supper exposes over MCP boils down to asking, checking, fetching, and grounding, in that order or however your agent needs them.

ask

Ask any data question in natural language. Returns a verified answer grounded in your semantic model.

// when you want a plain-language answer

get_pipeline_status

Check whether a query is still processing or has returned data. Poll after ask for complex questions.

// when ask returns "processing"

get_answer_rows

Retrieve structured row data behind a completed answer: columnar, ready for a chart, table, or downstream logic.

// when you need structured rows for a chart or logic

get_context

Retrieve semantic-model context: metric definitions, entity descriptions, available tables, before your agent asks.

// when an agent needs to understand a metric first

Authentication modes per agent archetype.

OAuth (interactive): for tools like Claude and Claude Code, a human authenticates once and the token is managed for them. Every query then runs under that person's existing Supper permissions, nothing extra to configure.

Service tokens (headless): for a backend job, a Slack bot, or your own app's server calling Supper on a schedule or on behalf of users. Generate a long-lived token, read it from environment or config, never hardcode it.

→ An app's service identity is permissioned exactly like any other Supper user. Restrict it to specific schemas, sources, tables, or even individual columns.
→ A customer-facing app is scoped to only the data it should ever surface, and Supper enforces that boundary at the query — your app layer never has to.
→ Serving several customer segments with different data boundaries from one app is a permissioning decision: give each segment its own scoped service account.

app.supper.co · service accounts · acme-app-prod

// service account permissions schema: crm_base ✓ visible table: opportunities ✓ visible column: deal_amount ✓ visible column: owner_email ✕ restricted table: contacts_pii ✕ restricted schema: billing ✕ restricted

Fig. B · A service account, scoped down to the column, same model as a human user.

Best practices.

Validation and live execution take real time. Design around it.

→ Don't block on ask for anything non-trivial. Poll get_pipeline_status.
→ Independent questions can run in parallel. Fire multiple ask calls concurrently rather than chaining them.
→ Nothing is cached outside your environment. Every call is a live query, every time.

§ 04

Internal tools & customer-facing apps

Using our MCP internally & externally.

Internal tools

Slack bots, reporting agents, dashboards.

The calling person's identity carries through automatically. Permissions and audit trail map 1:1 to the Supper roles that already exist, no extra plumbing.

→ inherits an existing Supper role

Customer-facing apps

Verified answers, embedded in your product.

Your backend calls Supper as a service identity, scoped to the schema, table, or column. What's different: you choose the boundary up front, one scoped account or one per customer segment.

→ scoped by a dedicated service account

Works with

Claude Claude Code ChatGPT Copilot LangChain Bedrock + any MCP tool

§ 05

Your team stays in control

DIY access means finding out something broke after an agent already reported the wrong number.

Supper flips that. You see more than a DIY pipeline shows you, and nobody on your team writes a new integration to get there.

Permissioned like infrastructure

AWS-IAM-style control, down to the column, term, category, and skill level. Internal usage and external-facing agent workflows can carry different rules.

One semantic model, every consumer

Human users, dashboards, workflows, and agents all draw from the same definitions. No drift between what the CEO sees and what an agent decides on.

Full audit trail

Every query an agent runs, logged. What was asked, what was returned, which definitions and permissions applied.

No maintenance tax on your team

DIY teams reported accuracy dropping from ~95% to ~65% in a month once schema changes outran doc updates. Supper's FDA absorbs that upkeep permanently; your engineers don't inherit it.

Proactive data-quality flags

Supper can surface broken syncs, stale CRM data flowing into the warehouse, or numbers that don't make sense, like outflows exceeding AUM, before an agent acts on bad data.

Cost and usage visibility

See which agents query what, how often, and at what token cost. Runaway workflows surface before they show up on the bill.

§ 06

Developer FAQ

Common questions.

Q. Do I need a human to authenticate every time?

A. No. For backend or headless use, generate a service token once and read it from your environment. OAuth is only needed for interactive tools like Claude or Claude Code.

Q. How fast is "fast"?

A. Simple lookups: ~10–20 seconds. Complex, multi-table questions: up to 60–120 seconds. Poll for status rather than holding a connection open; parallelize independent questions rather than chaining them.

Q. Can I go from a working prototype straight to production?

A. Yes, that's the intended path. Test the question in plain English, inspect the real rows, then harden that exact query into your endpoint. You're validating against real data, not reverse-engineering a schema first.

Q. What happens if my end users aren't Supper users themselves?

A. Your app's backend calls Supper as a service identity that stands in for the app itself. Permission that identity, by schema, table, or column, to exactly what the app should surface. Serving multiple customer segments typically means one scoped service account per segment.

Q. Which plans include MCP access?

A. Scale and Enterprise. Full tool reference, parameter schemas and response formats, lives in the API reference section of the wiki.

Next Step

Build on your data brain.

Full documentation — the connection guide, the permissioning model, and worked examples for Claude, Claude Code, and headless agent workflows — is available on request.