Superbrain Schema Context

A proof of concept for one feature: an MCP server that gives Superbrain's coding agent live, on-demand access to a connected database's schema, instead of dumping the whole schema into context up front. The UI is a thin shell around it, styled to match Superbrain's real interface, so the feature can be evaluated in something close to its real home.

What this is (and isn't)

• Real and working: the MCP server (/api/mcp), its 5 schema-retrieval tools, the Postgres introspection behind them, and the live agent demo that shows what the coding agent actually fetches while it builds.
• Placeholder: the rest of the IDE chrome (menus, other panels) and every data source except Postgres in the "Connect a data source" modal. These exist to show where this feature would live inside the real product, not to be functional.
• The in-app guided tour says this explicitly on first load, so an evaluator isn't guessing which parts to take seriously.

Why this feature

Superbrain's own pitch is a context engine that compresses and prioritizes code intelligence to cut token usage 60-80% while keeping full repo awareness. Database schema is the same problem one layer down: an agent building a data app needs table/column/relationship context to write correct code, and the naive approach — handing it the full schema as one blob — is exactly the kind of undifferentiated context bloat Superbrain's architecture is designed to avoid for code. This POC applies the same idea to schema: retrieve progressively, scoped to what the current step actually needs, instead of dumping everything up front.

Architecture

┌─────────────────┐     MCP (Streamable HTTP)     ┌──────────────────────┐
│  Groq              │ ─────────────────────────────▶│  /api/mcp             │
│  (Responses API,    │◀─────────────────────────────│  (mcp-handler)        │
│  remote MCP tool)    │        tool calls/results     │  5 schema tools       │
└─────────────────┘                                └──────────┬───────────┘
        ▲                                                      │
        │ prompt + trace                                       │ SQL (pg)
        │                                                       ▼
┌─────────────────┐                                ┌──────────────────────┐
│  Next.js UI       │──POST /api/agent─────────────▶│  Demo Postgres         │
│  (IDE-shell)      │                                │  (e-commerce schema)  │
└─────────────────┘                                └──────────────────────┘

The agent side runs on Groq's Responses API (openai/gpt-oss-120b), using Groq's native remote MCP support: you hand Groq an MCP server URL and it handles tool discovery, calling, and feeding results back to the model server-side, in one API call — no client-side orchestration loop to write. This is functionally the same shape as Anthropic's MCP connector or OpenAI's remote MCP API; Groq's implementation is explicitly built to be a drop-in swap for either. Which model/provider sits behind /api/agent is intentionally decoupled from the MCP server itself — /api/mcp never changes when the LLM provider changes, which is the whole point of building this as a real MCP server instead of a provider-specific tool-calling shim.

The five MCP tools (lib/schema-context.ts, exposed via app/api/mcp/route.ts):

Tool	Purpose	Cost
list_tables	Table names, approximate row counts, one-line comments. Nothing else.	Cheapest — always the first call.
search_schema	Keyword-ranked table search ("orders and payments" → relevant tables only).	Cheap — replaces manual scanning of list_tables output.
get_table_schema	Full columns/types/keys, but only for the table names passed in.	Scoped — never returns the whole DB.
get_related_tables	One-hop FK graph around a table, both directions.	Scoped — the local join graph, not the full ERD.
get_sample_values	A few real distinct values for one column.	Scoped — for enum/status columns, capped at 10.

Each tool result carries an estimated token count back to the UI, so the Context Panel can show exactly what the agent fetched, in what order, and at what cost — and compare that running total against what a naive "dump the whole schema as DDL" approach would have cost for the same database (getFullSchemaDump / getNaiveDumpTokenEstimate in lib/schema-context.ts).

Key design decisions

• Progressive disclosure over embeddings, for this POC. search_schema uses keyword/comment matching, not vector search. The tool contract (query in, ranked tables out) is what matters and is what a production version would keep; swapping the scoring function for embeddings is an internal implementation change, not an interface change. Keyword search was enough to demonstrate the pattern without adding an embeddings pipeline to a one-day build.
• Server-side connection string, not client-supplied. The datasource modal displays the demo Postgres credentials for transparency, but the actual connection is made server-side via DEMO_DATABASE_URL. Letting a public demo app accept arbitrary client-supplied connection strings is a real security problem (SSRF into internal networks, credential harvesting) — not a corner worth cutting even in a demo.
• One live data source, by design, not by omission. Redshift/Snowflake/Synapse/ BigQuery appear in the picker because that's what the real product's picker would show, but only Postgres is wired up. The tool contract above is database-agnostic (it's just table/column/FK/sample-value retrieval); adding a second source means writing a new introspection module behind the same five tools, not redesigning the feature.
• MCP over a bespoke API. Using the actual Model Context Protocol (via mcp-handler on Vercel, and Groq's native remote-MCP support on the model side) instead of a custom tool-calling shim means this server would work unmodified if Superbrain's own agent — or any other MCP-speaking agent/provider — connected to it. Swapping the LLM provider (this started as Anthropic, now runs on Groq) only touched /api/agent; /api/mcp didn't change at all. That portability is the actual point of building it as an MCP server instead of an API route the agent calls directly.
• Groq's Responses API, not Chat Completions. Groq explicitly recommends the Responses API for MCP workflows — tool discovery, reasoning, and tool calls come back as distinct, labeled steps in output[], which is what makes the Context Panel's trace possible without extra parsing gymnastics.
• Single non-streaming agent call for the demo. /api/agent waits for the full Claude response (including all MCP tool round-trips) before returning, rather than streaming. Simpler to build and debug correctly in the time available; streaming the tool-call trace live is the first thing I'd add next (see below).
• API key stays client-side, in memory only. The evaluator pastes their own Groq key into the app; it's sent straight to this app's own /api/agent route per-request and never written to storage or logs. A demo app shouldn't ship a real production key in a public repo.

Running it

npm install
cp .env.example .env.local   # fill in DEMO_DATABASE_URL
npm run seed                  # seeds the demo e-commerce schema (12 tables)
npm run dev

Open http://localhost:3000 → "Connect a Data Source" → PostgreSQL → Connect.

Note on testing the live agent call locally: Groq's servers need to reach your MCP server over a public HTTPS URL — localhost isn't reachable from their side. The agent demo (asking it to build something) only works once deployed (or through a tunnel like ngrok http 3000 pointed at your local server, with the origin detection adjusted accordingly). The MCP server itself and the DB introspection can be fully tested locally via /api/db/connect and by calling /api/mcp directly with the MCP protocol — both are covered above and don't need Groq at all.

Demo database

Any Postgres works. Free options: Neon or Supabase. Create a read-only role for the connection string used in the app:

create role demo_reader with login password 'your_password';
grant connect on database superbrain_demo to demo_reader;
grant usage on schema public to demo_reader;
grant select on all tables in schema public to demo_reader;

Deploying

1. Push this repo to GitHub.
2. Import it into Vercel.
3. Set DEMO_DATABASE_URL, NEXT_PUBLIC_DEMO_DB_HOST, NEXT_PUBLIC_DEMO_DB_NAME, NEXT_PUBLIC_DEMO_DB_USER as environment variables in the Vercel project.
4. Deploy. The MCP server is reachable at https://<your-app>.vercel.app/api/mcp automatically — /api/agent derives that URL from the incoming request, so no extra config is needed for the two to find each other.

---

Product Strategy

A. If you were building this product, what would you change or add next, and why?

The thing I'd prioritize next is exactly what the POC is built around: reducing token usage inside the iterative build loop by giving the agent proper, task-specific context about the data it's working with not just code context, but data-platform context before it starts generating. Right now, if an agent has to write code against a database without that context, it burns tokens and time discovering the schema through trial and error via failed syntax and logic checks. Baking a lightweight, on-demand schema/data-context retrieval layer into the core Architecture engine the same way Token Fold handles code context would extend the token-reduction story to data-heavy tasks specifically, and should also lift correctness, since the agent isn't guessing at what it can't see.

• Streaming the agent's tool-call trace live into the Context Panel instead of waiting for the full response, so the "what is it fetching right now" moment reads as live, not retrospective — closer to how Superbrain's own product presumably shows its context engine working.
• Swapping search_schema's keyword matching for embeddings once a schema is large enough that keyword overlap stops being a good relevance signal (dozens+ of tables, ambiguous naming) — the tool contract doesn't change, only what's behind it.
• A caching/diffing layer so a long agent session doesn't re-pay full token cost for schema it already retrieved earlier in the same session, only the delta.
• Extending the same 5-tool contract to the other listed data sources (Redshift, Snowflake, Synapse, BigQuery) — each needs its own introspection module (different system catalogs/information_schema quirks) but the same interface.

B. What major UI issues do you dislike, and how do you think they annoy current users?

The UI, honestly, looks almost identical to VS Code and I think that's a missed opportunity more than a safe choice. VS Code forks are common, but the ones that stand out have a visual identity of their own, not just a different logo on the same shell the way PyCharm feels distinct from VS Code even though both are IDEs. I'd invest in giving Superbrain its own visual language, something that signals “this is a different way of working,” not “this is VS Code with an AI panel.” Beyond looks, I think the bigger opportunity is becoming a genuinely centralized workspace not just for writing code, but for the whole path from data to product: data transformation, BI/analytics building, and app building and deployment, all inside one place. Right now that work is scattered across separate tools, and every handoff between them is friction and context loss. If Superbrain became the place developers default to for that entire loop instead of just the coding step, it stops being “yet another AI IDE” and becomes the tool people build their whole workflow around.

---

What I built and why

Before writing any code, I spent time going through the Superbrain IDE and researching what makes it different from other coding assistants like Codex and Claude Code. The core differentiator I found was Token Fold the technique behind the claimed 60–80% token reduction. But going through it, I noticed a trade-off: relative to Codex and Claude Code, Superbrain seemed to fall slightly behind on correctness the ability to get things right without as many back-and-forth attempts likely a consequence of operating with less context. That felt like the real gap worth exploring. Coding agents build code iteratively: generate, check syntax, check logical correctness, loop back if something's wrong. Every failed loop costs tokens and time. If the agent already has the right context up front specifically, the schema of whatever data platform it's working against a lot of those failed loops shouldn't happen in the first place. So instead of compressing everything and hoping the model infers what it needs, I wanted to equip the agent with tools to retrieve exactly the schema context it needs, when it needs it. That's the gap the POC explores: give the agent narrow, on-demand access to database schema, so it has enough context to be accurate early, without paying the token cost of dumping the whole schema up front reducing cost and reducing the number of failed iterations at the same time.

Decision-making log

I spent about a day researching before writing any code going through Superbrain, reading about Token Fold, and comparing it against Codex and Claude Code to understand where the actual gap was, before deciding what to build. On the stack: I'm primarily a Python developer, and my default for building MCP servers is FastMCP. For this project, though, I stuck with a single TypeScript/Next.js stack instead of a separate Python FastMCP service talking to a Next.js frontend. Two languages means two runtimes and a network hop between them more moving parts to keep in sync for what's meant to be a focused POC. A same-process MCP server inside the Next.js app avoided that overhead entirely, and is also faster than an inter-process call out to a separate FastMCP service would have been. The core product decision was to build one feature end to end progressive schema retrieval for iterative query-building loops properly, and be upfront in the UI that the rest of the shell (Explorer, Search, Source Control, Run, Extensions) is unwired placeholder, rather than spreading effort thin faking a full IDE.