MySQL용 vsql_mcp 확장 기능

vsql_mcp는 서버 프로세스 안의 리스너에서 Model Context Protocol을 통해 AI 에이전트에게 데이터베이스를 제공합니다. 에이전트는 스키마를 나열하고, 테이블을 설명하고, 읽기 전용 쿼리를 실행할 수 있습니다. 쓰기는 켜기 전까지 꺼져 있으며, 쿼리 경로는 사용자가 지정한 데이터베이스 계정을 통해 실행되므로, 에이전트는 그 계정에 부여한 접근 권한을 정확히 그대로 갖습니다.


관리자	VillageSQL
소스 및 전체 문서	villagesql/vsql-mcp
라이선스	GPL-2.0
작성 언어	Rust
기능 단계	미리 보기

이 확장 기능은 미리 보기 기능 네 가지를 사용하므로, 서버를 --vsql_allow_preview_extensions=ON으로 시작해야 합니다. 그렇지 않으면 INSTALL EXTENSION이 거부됩니다.

설치

vsql_mcp는 서버와 함께 번들로 제공되지 않으므로, 먼저 저장소에서 빌드한 다음 생성된 vsql_mcp.veb를 veb_dir 시스템 변수가 가리키는 디렉터리에 복사하세요. 그런 다음 설치합니다:

INSTALL EXTENSION vsql_mcp;

설치되었는지 확인합니다:

SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_mcp';

+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_mcp       |
+----------------+

빌드 지침은 저장소에 있습니다.

추가되는 기능

리스너가 무엇을 하고 있는지 보고하는 SQL 함수 info() 하나를 추가합니다. 나머지는 모두 구성과 MCP 트래픽입니다.

SELECT CONVERT(info() USING utf8mb4) AS info;

{"enabled":false,"http_port":0,"https_port":0,"port":3100,"protocol_version":"2025-06-18","schema":"","sessions_active":0,"ssl_port":3143,"starting":false}

starting은 vsql_mcp.vsql_mcp_enabled를 ON으로 설정한 순간부터 백그라운드 워커가 다음에 깨어날 때까지 true이며, 워커는 25ms마다 깨어납니다. 이 구간에서 호출하면 리스너가 아직 바인딩되지 않았으므로 "enabled":false로 보고될 수도 있습니다.

설정	기본값	제어 대상
`vsql_mcp.vsql_mcp_enabled`	`OFF`	리스너 실행 여부
`vsql_mcp.schema`	비어 있음	제공할 데이터베이스
`vsql_mcp.db_url`	비어 있음	쿼리, 쓰기, explain 도구가 연결에 사용하는 계정
`vsql_mcp.allowed_tables`	비어 있음	해당 도구가 접근할 수 있는 테이블
`vsql_mcp.allow_write`	`OFF`	쓰기 도구의 존재 여부
`vsql_mcp.max_rows`	`1000`	결과 하나의 행 수 상한
`vsql_mcp.query_timeout`	`30`	쿼리 하나가 실행될 수 있는 시간(초)
`vsql_mcp.port`	`3100`	HTTP 포트
`vsql_mcp.ssl_port`	`3143`	HTTPS 포트
`vsql_mcp.ssl_cert`, `vsql_mcp.ssl_key`	비어 있음	HTTPS용 인증서와 키
`vsql_mcp.require_auth`	`OFF`	요청에 bearer 토큰이 필요한지 여부
`vsql_mcp.bearer_token`	비어 있음	해당 토큰
`vsql_mcp.session_ttl`	`1800`	유휴 에이전트 세션을 유지하는 시간(초)

예제

리스너를 데이터베이스에 연결하고 시작합니다:

SET GLOBAL vsql_mcp.schema = 'shop';
SET GLOBAL vsql_mcp.db_url = 'mysql://agent:secret@127.0.0.1:3306/shop';
SET GLOBAL vsql_mcp.allowed_tables = 'orders,customers';
SET GLOBAL vsql_mcp.vsql_mcp_enabled = ON;

그러면 에이전트가 MCP Streamable HTTP로 http://127.0.0.1:3100에 연결합니다. 저장소에 각 에이전트용 클라이언트 구성이 있습니다.

db_url의 계정이 에이전트가 할 수 있는 일의 상한을 정하며, 모든 데이터베이스 계정이 SHOW VARIABLES로 비밀번호를 포함한 db_url을 읽을 수 있으므로, 필요한 최소 권한만 부여하고 의도하기 전까지는 allow_write를 꺼 두세요. localhost 밖에서 포트에 접근할 수 있게 되기 전에 bearer 토큰과 함께 require_auth를 켜세요. SHOW VARIABLES는 그 토큰도 모든 계정에 보여 줍니다.

SET PERSIST로 쓴 설정은 재시작 후에도 유지되지만, UNINSTALL EXTENSION이 이를 삭제합니다. 제거 후 다시 설치하면 모든 설정이 기본값으로 돌아가며, 재시작해도 이전 값은 돌아오지 않습니다.

참고 항목

MCP로 AI 에이전트에게 MySQL 제공하기 — 에이전트 연결과 에이전트가 볼 수 있는 것
확장 기능 관리 — 확장 기능 설정을 읽고 쓰는 방법
미리 보기 기능 — 미리 보기 플래그가 켜는 것과 보장하는 것
사용 가능한 확장 기능 — 전체 카탈로그
villagesql/vsql-mcp — 소스, 클라이언트 설정, 알려진 제한 사항

확장 기능 설치 및 실행

확장 기능 카탈로그

확장 기능 빌드

설치

추가되는 기능

예제

참고 항목

​설치

​추가되는 기능

​예제

​참고 항목

설치

추가되는 기능

예제

참고 항목