Convex MCP — 스키마·함수·데이터, Claude가 직접 열어보게 하기

Convex로 백엔드 짜다가 "이 테이블에 필드가 뭐가 있더라" 확인하려고 대시보드 열고, 함수 시그니처 까먹어서 코드 뒤지고 그런 적 있죠? AI한테 물어봐도 스키마를 모르니까 있지도 않은 필드를 지어내기도 하고요.

뭔데

Convex CLI에 기본으로 들어있는 MCP 서버예요. 따로 설치할 패키지가 아니라 Convex를 쓰고 있으면 이미 손 닿는 곳에 있습니다.

뭘 해결하나

제공하는 도구가 꽤 실용적입니다.

• status — 지금 접근 가능한 배포(deployment) 목록 확인
• tables — 테이블별 선언된 스키마와 실제 데이터에서 추론된 스키마를 같이 보여줌
• data — 테이블 데이터를 페이지 단위로 조회
• functionSpec — 백엔드 함수 전체 목록과 인자·반환값 나열
• runOneoffQuery — 샌드박스에서 즉석 JS 쿼리 실행
• envList / envGet / envSet / envRemove — 환경변수 조회·수정

예를 들어 "users 테이블에 이메일 인증 상태 필드 있어?"라고 물으면 Claude가 tables 도구로 직접 스키마를 열어보고 대답합니다. 함수 이름이 헷갈릴 때도 functionSpec으로 실제 시그니처를 확인한 뒤 코드를 짜니까, 있지도 않은 API를 지어내는 일이 확 줄어요.

어떻게 시작하나

Claude Code나 Cursor에서는 Convex 플러그인을 설치하면 MCP 서버가 자동으로 켜집니다. 수동으로 붙이고 싶다면 한 줄이면 됩니다.

```

npx -y convex@latest mcp start

```

언제 쓰고 언제 쓰지 마라

Convex를 백엔드로 쓰는 프로젝트라면 거의 기본 장착급입니다. 스키마와 함수 컨텍스트를 Claude가 직접 읽으니 헛다리 짚는 코드가 확실히 줄어들어요.

당연히 다른 DB 스택이면 의미 없고, 이 도구도감에도 이미 Neon MCP나 Stripe MCP처럼 각 서비스 전용 MCP들이 따로 있으니 자기 스택에 맞는 걸 찾으면 됩니다. 그리고 runOneoffQuery는 진짜로 배포된 데이터에 쿼리를 날리는 기능이라, 프로덕션 배포에 무심코 물려두고 아무 쿼리나 실행시키는 건 주의가 필요해요.

한계

공식 문서가 도구별 세부 옵션까지는 자세히 다루지 않아서, 어디까지 데이터 접근을 열어줄지는 직접 켜보면서 감을 잡아야 합니다.

출처: [Convex MCP Server (공식 문서)](https://docs.convex.dev/ai/convex-mcp-server)