MCP를 통해 에이전트에 Supabase 연결하기

MCP(Model Context Protocol)를 사용하면 Claude Code가 외부 도구에 연결하고 대화 중에 직접 사용할 수 있어요. Supabase는 데이터베이스, Edge Functions, 인증 등 다양한 리소스를 에이전트에 노출하는 공식 MCP 서버를 제공해요. 이 레슨에서는 토큰 생성부터 터미널에서의 첫 번째 테스트까지 안내해요.

Personal access token 생성하기

Supabase MCP 서버는 특정 프로젝트가 아닌 Supabase 계정에 연결된 personal access token으로 인증해요. 토큰 하나로 모든 프로젝트에 접근할 수 있어요.

1. Supabase 대시보드를 열고, 왼쪽 하단의 아바타를 클릭한 후 Account > Access Tokens으로 이동해요.
2. Generate new token을 클릭해요.
3. 이름을 명확하게 입력해요. 예: claude-code-mcp.
4. 창을 닫으면 다시 볼 수 없으니 토큰을 즉시 복사해요.

Claude Code에 MCP 서버 추가하기

Supabase MCP 서버는 HTTP 모드로 동작해요. https://mcp.supabase.com/mcp 주소의 Supabase 서버에서 실행돼요. 로컬에 아무것도 설치할 필요가 없어요. Claude Code에 서버 위치와 인증 방법만 알려주면 돼요.

CLI 명령어를 통해 (권장)

$claude mcp add --transport http supabase  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

YOUR_ACCESS_TOKEN을 방금 생성한 토큰으로 교체해요. 이 명령어는 기본적으로 local 스코프로 Claude Code 설정에 서버를 등록해요(이 컴퓨터의 해당 사용자에게만 적용).

.mcp.json 파일을 통해 (팀과 설정 공유할 때)

버전 관리 프로젝트에서 작업하고 팀 전체가 MCP 서버를 사용하게 하려면 프로젝트 루트에 .mcp.json 파일을 만들어요:

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SUPABASE_ACCESS_TOKEN}"
      }
    }
  }
}

${SUPABASE_ACCESS_TOKEN} 표기법은 셸의 환경 변수에서 자동으로 해석돼요. 팀원 각자가 자신의 변수를 내보내면, 토큰이 저장소에 포함되지 않아요.

연결 확인하기

서버를 추가한 후 Claude Code에서 정상적으로 인식되는지 확인해요.

$claude mcp list

목록에 URL과 함께 supabase가 표시되어야 해요. 더 확인하려면 Claude Code를 실행하고 /mcp를 입력해요. 각 서버의 실시간 상태(연결됨, 대기 중, 오류)와 사용 가능한 도구 수를 볼 수 있어요.

첫 번째 쿼리 테스트하기

터미널에서 Claude Code를 실행한 후 Supabase 데이터베이스를 조회하는 질문을 해봐요.

$claude

채팅 인터페이스가 열리면 이 프롬프트를 입력해봐요:

내 Supabase 프로젝트의 테이블 목록을 나열하고 구조를 설명해줘.

계정에 여러 프로젝트가 연결되어 있다면 Claude Code가 어느 것을 사용할지 물어볼 거예요. 설정의 MCP 서버 URL에 ?project_ref=YOUR_PROJECT_REF를 추가해서 처음부터 특정 프로젝트를 지정할 수도 있어요.

MCP 서버가 할 수 있는 것

서버는 기본적으로 활성화된 여러 도구 그룹을 노출해요:

• Database: 테이블과 확장 기능 나열, 마이그레이션 로그 읽기, 임의의 SQL 실행.
• Development: API URL 가져오기, 공개 키 조회, TypeScript 타입 생성.
• Edge Functions: 함수 나열, 검사 및 배포.
• Debugging: 서비스 로그와 보안 권고 사항 확인.
• Docs: 에이전트에서 직접 Supabase 문서 검색.

Storage 그룹은 기본적으로 비활성화되어 있어요. Branching 그룹은 유료 플랜이 필요해요.