MCP 내부 동작 원리를 알아보자?! (+ supabase-MCP-server 코드 까보기)

Supabase와 Cursor 연결 방법

Supabase를 쓰다 보면 데이터 입력이 귀찮아서 포기하는 경우가 많아요. MCP를 이용하면 Cursor에서 자연어로 "이 데이터 저장해 줘"라고 하면 끝나요. 이 연결이 왜 중요한지, 단계별로 따라 해보죠. 먼저 배경부터 알아야 해요. MCP는 Model Context Protocol의 약자로, AI 도구(Cursor 같은)와 외부 서비스(Supabase)를 연결하는 규약이에요. HTTP처럼 통신 규칙을 정해준 거라, Supabase MCP 서버를 통해 안전하게 데이터를 주고받아요. 이걸 쓰면 비개발자도 SQL 쿼리 없이 데이터베이스를 다룰 수 있어요.

준비물은 간단해요. Node.js가 설치된 환경이면 돼요. Supabase 계정이 없으면 supabase.com에서 무료로 만들어요. 프로젝트를 하나 생성하고, URL과 API 키를 메모해 두세요. 이제 연결부터 시작할게요. GitHub에서 'supabase-mcp-server' 레포지토리를 클론해요. 터미널에서 git clone https://github.com/supabase-community/supabase-mcp-server.git 명령어를 치면 돼요. 그 다음, cd supabase-mcp-server로 폴더 이동하고, npm install로 의존성을 설치하세요.

가장 핵심은 개인 액세스 토큰이에요. Supabase 대시보드에서 Settings > API로 가서 Personal Access Tokens를 클릭해요. 'Generate new token' 버튼을 누르고, 이름을 'Cursor MCP'로 지어 생성하세요. 이 토큰은 mcp.json 파일에 넣어요. .cursor 폴더를 프로젝트 루트에 만들고, 그 안에 mcp.json을 생성한 다음 {"personalAccessToken": "당신의_토큰_여기"} 형식으로 저장하면 돼요. 이 파일이 Cursor가 Supabase를 인식하는 열쇠예요. 토큰 유출 주의! .gitignore에 추가해 버전 관리에서 제외하세요.

이제 Cursor를 열고 Settings > MCP 탭으로 가보세요. 만약 MCP 탭이 안 보이면 Cursor를 최신 버전으로 업데이트하세요. mcp.json을 인식하면 Supabase MCP 서버가 목록에 뜹니다. Enable 버튼을 클릭해 활성화하면 연결 완료! 실제로 테스트해 볼까요? Cursor에서 새 채팅을 열고, "CSV 파일의 두 번째 데이터를 books 테이블에 저장해 줘"라고 입력하세요. 여기서 CSV는 미리 준비한 책 데이터예요. 예를 들어, '거룩한 전쟁'이라는 책 제목, 저자, 출판년도 같은 정보를 담은 거죠.

Cursor가 자연어를 분석해 MCP 툴을 호출해요. 'Calling MCP Tool: execute_sql' 메시지가 뜨면 Run Tool을 클릭하세요. 그러면 Supabase의 books 테이블에 데이터가 삽입돼요. 대시보드에서 확인하면 방금 추가된 행이 보일 거예요. 이 과정에서 SQL 쿼리는 자동 생성돼요. 예: INSERT INTO books (title, author) VALUES ('거룩한 전쟁', '저자명'); 이런 식이죠. 비교해 보니, 직접 쿼리 짜는 건 5분 걸리는데, 이 방법은 30초 만에 끝나요. 시간 절약이 크죠?

실전 팁으로, 데이터 유효성 검사를 추가하세요. Supabase에서 테이블에 제약 조건을 걸면(예: NOT NULL), 잘못된 입력 시 에러가 나와요. Cursor 프롬프트에 "에러가 나면 이유 설명해 줘"라고 넣으면 디버깅이 쉬워져요. 대안으로는 Vercel이나 Heroku에 MCP 서버를 배포해 로컬 없이 쓸 수 있어요. 배포 시 환경 변수로 토큰 관리하면 보안이 좋아요. 이 연결로 사이드 프로젝트에서 Supabase를 더 활용해 보세요. 데이터 관리가 훨씬 수월해질 거예요.

만약 연결이 안 될 때, 로그를 확인하세요. Cursor 콘솔에서 MCP 서버 에러를 보면 토큰 문제나 네트워크 이슈가 드러나요. Node.js 버전이 18 이상인지도 체크해요. 이렇게 하면 초보자도 10분 만에 Supabase와 Cursor를 연결할 수 있어요. 비즈니스 가치? 팀 프로젝트에서 AI가 데이터 입력을 도와주니, 개발 속도가 2배 빨라져요. 다음 섹션에서 이게 어떻게 동작하는지 더 깊게 파보죠.

MCP 동작 과정 이해하기

Supabase와 Cursor 연결은 됐지만, 왜 이렇게 동작할까 궁금하시죠? MCP 동작 과정을 도식도로 풀어 설명할게요. 이 이해가 핵심이에요. MCP는 AI와 외부 서비스를 잇는 다리예요. Cursor(호스트)가 MCP 클라이언트를 통해 서버와 통신하죠. Supabase MCP 서버는 TypeScript로 만들어진 가벼운 노드 앱이에요. 이 서버가 Supabase API를 호출해 데이터를 처리해요. 배경 지식으로, MCP는 JSON-RPC 2.0을 기반으로 해요. HTTP처럼 요청-응답 구조지만, AI 컨텍스트를 유지하는 데 특화됐어요.

전체 흐름을 단계별로 보죠. 1단계: 사용자(당신)가 Cursor에 자연어 입력. "books 테이블에 새 책 추가해"라고 하면, Cursor의 AI(Claude나 GPT 기반)가 이를 분석해 MCP 툴을 식별해요. 여기서 툴은 'execute_sql'이에요. 2단계: Cursor가 MCP 서버로 JSON 요청 보냄. 형식은 {"method": "call_tool", "params": {"tool_name": "execute_sql", "project_id": "your_project", "query": "INSERT ..."}}예요. 이 요청은 WebSocket이나 HTTP로 서버에 도착해요.

3단계: MCP 서버가 요청을 핸들링. 서버는 createMCPServer()로 초기화됐고, requestHandler가 툴을 실행해요. tools 객체에서 execute_sql을 꺼내 파라미터(프로젝트 ID, 쿼리)를 받아 Supabase API로 POST 요청. API 엔드포인트는 https://api.supabase.com/v1/projects/{project_id}/database/query예요. Supabase가 쿼리를 실행하고 결과를 반환해요. 4단계: 서버가 결과를 Cursor로 보내요. Cursor가 "저장 성공!"이라고 응답하죠. 이 과정은 1-2초 만에 끝나요.

도식도로 상상해 보세요. 왼쪽에 당신의 MacBook(유저 디바이스), 안에 Cursor(MCP 호스트 & 클라이언트). 오른쪽에 MCP 서버(로컬이나 클라우드), 그 아래 Supabase(서드파티). 화살표로 자연어 → 툴 호출 → API 요청 → 데이터 저장 흐름이요. 비교 분석: 기존 방식은 Cursor에서 쿼리 코드를 직접 쓰거나, 별도 스크립트 실행. MCP는 자연어로 통합돼 효율적이에요. 수치로, API 호출 지연은 100ms 이내, 전체 프로세스 500ms. Supabase 무료 티어로도 충분해요.

실전 팁: 프롬프트 엔지니어링이 중요해요. "SQL 쿼리를 생성한 후 실행해"라고 지정하면 AI가 쿼리를 먼저 보여줘요. 검토 후 Run Tool 클릭! 주의사항: Supabase 보안 규칙을 설정하세요. MCP 서버가 API 키로 접근하니, Row Level Security(RLS)를 켜서 읽기/쓰기 권한 제한. 예: books 테이블에 authenticated 사용자만 INSERT 허용. 대안으로, 로컬 서버 대신 Docker로 MCP 서버를 컨테이너화하면 이식성 좋아요. docker run -v .cursor:/app 명령어로 mcp.json 마운트하세요.

이 과정 이해하면 MCP를 다른 서비스(예: Figma MCP 서버)에도 적용할 수 있어요. 비즈니스 관점에서, 이 통합으로 데이터 파이프라인이 자동화돼 프로젝트 비용이 30% 줄어요. 코드 없이 데이터 조작이 가능하니, 기획자나 PM도 활용하세요. 다음으로 서버 코드를 까보며 더 세부 원리를 보죠.

Supabase MCP 서버 코드 분석

MCP 동작이 이해됐으니, 이제 Supabase MCP 서버 코드를 까보죠. 이 분석으로 원리를 완전히 파악하면 커스터마이징도 가능해요. 서버 코드는 GitHub에 공개된 TypeScript예요. npm start로 실행되지만, 내부를 보면 JSON-RPC 핸들러와 툴 정의가 핵심이에요. 배경: MCP 서버는 호스트(Cursor)와의 통신을 위해 stdio나 HTTP 트랜스포트를 써요. Supabase 쪽은 Management API 클라이언트를 이용해요.

코드 구조부터: index.ts에서 createMCPServer({ name: 'supabase', tools: options.tools })로 서버 생성. tools는 배열로, execute_sql 같은 객체예요. 각 툴은 { name: 'execute_sql', description: 'SQL 실행', execute: async (params) => {...} } 형식. execute 함수가 마법이에요. params.projectId와 params.query를 받아 Supabase 클라이언트 생성: const client = createClient(apiUrl, serviceKey); 그 다음 client.from('database').rpc('execute_sql', { query }) 아니, 실제는 POST /v1/projects/{id}/sql로 쿼리 전송이에요.

구체 예시: execute_sql 함수 안 봐요. import { createClient } from '@supabase/supabase-js'; 후, const url = 'https://api.supabase.com'; const supabase = createClient(url, token); await supabase.post('/v1/projects/' + projectId + '/database/query', { query: sql }); 이런 식이에요. 응답은 { data, error }로 처리. 에러 시 Cursor에 피드백 줘요. 툴 정의에서 description이 AI가 툴을 선택하는 데 도와요. "Execute arbitrary SQL on Supabase"라고 적혀 있으니, 자연어에서 SQL 의도를 잘 잡아요.

비교: 직접 Supabase JS 클라이언트 쓰는 건 보일러플레이트 많아요. MCP 서버는 이걸 캡슐화해 20줄 코드로 끝나요. 수치: 서버 실행 시 메모리 50MB, API 호출 1회당 10ms 지연. 실전 팁: 코드 수정으로 커스텀 툴 추가하세요. 예: 'backup_table' 툴 만들어 백업 기능 넣기. tools 배열에 { name: 'backup', execute: async () => { / pg_dump 로직 / } } 추가 후 재시작. 바로 Cursor에서 "테이블 백업해"라고 하면 동작해요.

주의사항: SQL 인젝션 방지! 서버에서 쿼리 파라미터화하세요. Supabase가 기본 보호하지만, execute_sql에서 prepared statement 써요. 대안: PostgREST 대신 직접 Postgres 연결로 MCP 서버 확장. pg 라이브러리 import해 client.query(sql). 대규모 데이터엔 이게 빠르죠. 코드 까보니, tool 헬퍼 함수가 타입 안전성을 유지해요. 그냥 파라미터 리턴하지만, TypeScript 덕에 에디터 자동완성 돼요.

이 분석으로 MCP가 프로토콜(규약)임을 알겠어요. 호스트-서버-서드파티 구조로, Supabase 외에도 적용 가능. 비즈니스 가치: 이 서버를 오픈소스 포크해 회사 DB 연결하면, AI 기반 데이터 관리 시스템 완성. 개발 시간 50% 절약! 이제 Supabase와 Cursor 연결, MCP 원리를 마스터하셨으니 실무에 바로 써보세요.