Superbrain Schema-Context MCP — POC

하나의 기능에 대한 개념 증명(POC)입니다: Superbrain의 코딩 에이전트가 연결된 데이터베이스의 스키마에 실시간으로, 필요할 때 접근할 수 있게 해주는 MCP 서버 — 전체 스키마를 처음부터 컨텍스트에 통째로 던져넣는 대신 말이죠. UI는 그 주변을 감싸는 얇은 셸로, Superbrain의 실제 인터페이스와 일치하도록 스타일링되어 있어 실제 제품과 유사한 환경에서 이 기능을 평가할 수 있습니다.

이것이 무엇인가 (그리고 무엇이 아닌가)

• 실제로 동작하는 것: MCP 서버(/api/mcp), 5개의 스키마 조회 도구, 그 뒤에 있는 Postgres 인트로스펙션, 그리고 코딩 에이전트가 빌드하는 동안 실제로 무엇을 가져오는지 보여주는 라이브 에이전트 데모.

• 플레이스홀더: 나머지 IDE 크롬(메뉴, 기타 패널)과 "Connect a data source" 모달의 Postgres를 제외한 모든 데이터 소스. 이들은 이 기능이 실제 제품 안에서 어디에 위치할지를 보여주기 위해 존재할 뿐, 실제로 동작하지는 않습니다.

• 인앱 가이드 투어가 첫 로드 시 이 점을 명시적으로 알려주므로, 평가자가 어떤 부분을 진지하게 봐야 할지 헷갈리지 않습니다.

Related MCP server: keystone-mcp

이 기능이 필요한 이유

Superbrain의 핵심 제안은 코드 인텔리전스를 압축하고 우선순위를 매겨 토큰 사용량을 60-80% 줄이면서도 전체 저장소 인지력을 유지하는 컨텍스트 엔진입니다. 데이터베이스 스키마는 그보다 한 단계 아래의 동일한 문제입니다: 데이터 앱을 만드는 에이전트는 올바른 코드를 작성하기 위해 테이블/컬럼/관계 컨텍스트가 필요하며, 순진한 접근 방식 — 전체 스키마를 하나의 덩어리로 넘겨주는 것 — 은 정확히 Superbrain의 아키텍처가 코드에 대해 피하도록 설계된 종류의 무차별적 컨텍스트 비대화입니다. 이 POC는 동일한 아이디어를 스키마에 적용합니다: 모든 것을 처음부터 덤프하는 대신, 현재 단계가 실제로 필요로 하는 범위로 한정하여 점진적으로 검색합니다.

아키텍처

┌─────────────────┐     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)  │
└─────────────────┘                                └──────────────────────┘

에이전트 측은 Groq의 Responses API(openai/gpt-oss-120b)에서 실행되며, Groq의 네이티브 원격 MCP 지원을 사용합니다: Groq에 MCP 서버 URL을 넘기면 서버 측에서 도구 발견, 호출, 결과를 모델에 다시 공급하는 것을 단일 API 호출로 처리합니다 — 클라이언트 측 오케스트레이션 루프를 작성할 필요가 없습니다. 이는 기능적으로 Anthropic의 MCP 커넥터나 OpenAI의 원격 MCP API와 동일한 형태입니다; Groq의 구현은 명시적으로 둘 중 어느 것과도 드롭인 교체가 가능하도록 설계되었습니다. /api/agent 뒤에 어떤 모델/프로바이더가 있는지는 의도적으로 MCP 서버 자체와 분리되어 있습니다 — LLM 프로바이더가 변경되어도 /api/mcp는 절대 변경되지 않습니다. 이것이 프로바이더별 도구 호출 셰임 대신 실제 MCP 서버로 구축하는 핵심 이유입니다.

다섯 가지 MCP 도구(lib/schema-context.ts, app/api/mcp/route.ts를 통해 노출):

각 도구 결과는 추정 토큰 수를 UI로 다시 전달하므로 Context Panel은 에이전트가 무엇을, 어떤 순서로, 어떤 비용으로 가져왔는지 정확히 표시할 수 있습니다 — 그리고 동일한 데이터베이스에 대해 순진한 "전체 스키마를 DDL로 덤프" 방식이 들었을 비용과 누적 합계를 비교할 수 있습니다(lib/schema-context.ts의 getFullSchemaDump / getNaiveDumpTokenEstimate).

핵심 설계 결정

• 이 POC에서는 임베딩보다 점진적 공개(progressive disclosure). search_schema는 벡터 검색이 아닌 키워드/주석 매칭을 사용합니다. 도구 계약(쿼리 입력, 순위가 매겨진 테이블 출력)이 중요한 것이며 프로덕션 버전이 유지할 부분입니다; 점수 함수를 임베딩으로 교체하는 것은 인터페이스 변경이 아닌 내부 구현 변경입니다. 키워드 검색은 하루짜리 빌드에 임베딩 파이프라인을 추가하지 않고도 패턴을 입증하기에 충분했습니다.

• 클라이언트 제공이 아닌 서버 측 연결 문자열. 데이터소스 모달은 투명성을 위해 데모 Postgres 자격 증명을 표시하지만, 실제 연결은 DEMO_DATABASE_URL을 통해 서버 측에서 이루어집니다. 공개 데모 앱이 임의의 클라이언트 제공 연결 문자열을 수락하도록 하는 것은 실제 보안 문제(내부 네트워크로의 SSRF, 자격 증명 수집)입니다 — 데모에서도 잘라낼 가치가 없는 부분입니다.

• 하나의 라이브 데이터 소스 — 누락이 아니라 설계상. Redshift/Snowflake/Synapse/BigQuery는 실제 제품의 피커가 보여줄 것이기 때문에 피커에 나타나지만, Postgres만 연결되어 있습니다. 위의 도구 계약은 데이터베이스에 구애받지 않습니다(단지 테이블/컬럼/FK/샘플 값 검색일 뿐입니다); 두 번째 소스를 추가한다는 것은 동일한 5개 도구 뒤에 새 인트로스펙션 모듈을 작성하는 것을 의미하며, 기능을 재설계하는 것이 아닙니다.

• 맞춤형 API 대신 MCP. 실제 Model Context Protocol(Vercel에서 mcp-handler를 통해, 모델 측에서 Groq의 네이티브 원격 MCP 지원을 통해)을 맞춤형 도구 호출 셰임 대신 사용한다는 것은, Superbrain 자체 에이전트 — 또는 MCP를 말하는 다른 에이전트/프로바이더 — 가 연결하더라도 이 서버가 수정 없이 작동한다는 것을 의미합니다. LLM 프로바이더를 교체하는 것(Anthropic으로 시작해서 현재 Groq에서 실행)은 /api/agent만 건드렸습니다; /api/mcp는 전혀 변경되지 않았습니다. 그 이식성이 에이전트가 직접 호출하는 API 라우트 대신 MCP 서버로 구축하는 실제 이유입니다.

• Chat Completions가 아닌 Groq의 Responses API. Groq는 MCP 워크플로우에 Responses API를 명시적으로 권장합니다 — 도구 발견, 추론, 도구 호출이 output[]에서 별개의 레이블이 지정된 단계로 반환되며, 이것이 추가적인 파싱 작업 없이 Context Panel의 추적을 가능하게 합니다.

• 데모를 위한 단일 비스트리밍 에이전트 호출. /api/agent는 반환하기 전에 전체 Claude 응답(모든 MCP 도구 왕복 포함)을 기다리며, 스트리밍하지 않습니다. 주어진 시간 내에 올바르게 구축하고 디버깅하기 더 간단합니다; 도구 호출 추적을 라이브로 스트리밍하는 것이 다음에 추가할 첫 번째 항목입니다(아래 참조).

• API 키는 클라이언트 측, 메모리에만 유지. 평가자는 자신의 Groq 키를 앱에 붙여넣습니다; 이 키는 요청별로 이 앱 자체의 /api/agent 라우트로 직접 전송되며 저장소나 로그에 기록되지 않습니다. 데모 앱은 공개 저장소에 실제 프로덕션 키를 포함해서는 안 됩니다.

실행 방법

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

http://localhost:3000을 열고 → "Connect a Data Source" → PostgreSQL → Connect.

로컬에서 라이브 에이전트 호출 테스트에 대한 참고: Groq의 서버는 공개 HTTPS URL을 통해 MCP 서버에 도달해야 합니다 — localhost는 Groq 측에서 접근할 수 없습니다. 에이전트 데모(무언가를 빌드하도록 요청하는 것)는 배포 후에만 작동합니다(또는 로컬 서버를 가리키는 ngrok http 3000 같은 터널을 통해, 오리진 감지를 그에 맞게 조정). MCP 서버 자체와 DB 인트로스펙션은 /api/db/connect를 통해 그리고 MCP 프로토콜로 /api/mcp를 직접 호출하여 완전히 로컬에서 테스트할 수 있습니다 — 둘 다 위에서 다루었으며 Groq가 전혀 필요 없습니다.

데모 데이터베이스

모든 Postgres가 작동합니다. 무료 옵션: Neon 또는 Supabase. 앱에서 사용하는 연결 문자열에 대해 읽기 전용 역할을 생성하세요:

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;

배포

1. 이 저장소를 GitHub에 푸시합니다.

2. Vercel로 가져옵니다.

3. Vercel 프로젝트에서 DEMO_DATABASE_URL, NEXT_PUBLIC_DEMO_DB_HOST, NEXT_PUBLIC_DEMO_DB_NAME, NEXT_PUBLIC_DEMO_DB_USER를 환경 변수로 설정합니다.

4. 배포합니다. MCP 서버는 https://<your-app>.vercel.app/api/mcp에서 자동으로 접근 가능합니다 — /api/agent는 들어오는 요청에서 해당 URL을 파생하므로 둘이 서로를 찾기 위한 추가 구성이 필요 없습니다.

제품 전략

A. 이 제품을 만든다면 다음에 무엇을 변경하거나 추가하시겠습니까, 그리고 왜?

(여기에 직접 답변을 작성하세요 — 이 POC를 만들면서 얻은 몇 가지 솔직한 출발점:)

• 전체 응답을 기다리는 대신 에이전트의 도구 호출 추적을 Context Panel에 라이브로 스트리밍하여 "지금 무엇을 가져오고 있나"라는 순간이 사후적이 아닌 실시간으로 읽히게 — Superbrain 자체 제품이 컨텍스트 엔진 작동을 보여주는 방식에 더 가깝게.

• 스키마가 커져서 키워드 중복이 더 이상 좋은 관련성 신호가 되지 않을 때(수십 개 이상의 테이블, 모호한 명명) search_schema의 키워드 매칭을 임베딩으로 교체 — 도구 계약은 변경되지 않고 뒤에 있는 것만 변경됩니다.

• 긴 에이전트 세션이 같은 세션에서 이미 검색한 스키마에 대해 전체 토큰 비용을 다시 지불하지 않도록 캐싱/디핑 계층 추가 — 델타만 지불.

• 동일한 5-도구 계약을 다른 나열된 데이터 소스(Redshift, Snowflake, Synapse, BigQuery)로 확장 — 각각 자체 인트로스펙션 모듈(다른 시스템 카탈로그/information_schema 특성)이 필요하지만 동일한 인터페이스.

B. 어떤 주요 UI 문제가 마음에 들지 않으며, 그것이 현재 사용자에게 어떻게 불편을 준다고 생각하십니까?

(Superbrain에서 실제로 보낸 시간을 바탕으로 여기에 직접 답변을 작성하세요.)

무엇을 만들었고 왜 그런지

(직접 작성 — 이 특정 기능을 구축하기로 한 선택과 그것이 "Founding AI Engineer" 브리프에 왜 맞는지에 대해 자신의 말로 한두 문단.)

의사 결정 기록

(직접 작성 — 실제로 내린 결정과 트레이드오프의 순서; 위의 "핵심 설계 결정" 섹션이 출발점이지만, 이 섹션은 과제의 진정성 요청에 따라 자신의 목소리로 작성해야 합니다.)