> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MySQL용 vsql_mcp 확장 기능

> vsql_mcp 확장 기능은 Model Context Protocol을 통해 AI 에이전트에게 MySQL을 제공하며, 스키마 탐색, 읽기 전용 쿼리, 테이블 허용 목록, 행 수 상한을 지원합니다.

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

| | |
| - | - |
| **관리자** | VillageSQL |
| **소스 및 전체 문서** | [villagesql/vsql-mcp](https://github.com/villagesql/vsql-mcp) |
| **라이선스** | GPL-2.0 |
| **작성 언어** | Rust |
| **기능 단계** | 미리 보기 |

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

## 설치

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

```sql theme={null}
INSTALL EXTENSION vsql_mcp;
```

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

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_mcp';
```

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

빌드 지침은 [저장소](https://github.com/villagesql/vsql-mcp)에 있습니다.

## 추가되는 기능

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

```sql theme={null}
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` | 유휴 에이전트 세션을 유지하는 시간(초) |

## 예제

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

```sql theme={null}
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`에 연결합니다.
저장소에 각 에이전트용 클라이언트 구성이 있습니다.

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

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

## 참고 항목

* [MCP로 AI 에이전트에게 MySQL 제공하기](https://villagesql.com/docs/en/guides/mysql-ai-agents-mcp.md) — 에이전트 연결과 에이전트가 볼 수 있는 것
* [확장 기능 관리](https://villagesql.com/docs/ko/extensions/managing.md) — 확장 기능 설정을 읽고 쓰는 방법
* [미리 보기 기능](https://villagesql.com/docs/ko/extensions/build/preview-capabilities.md) — 미리 보기 플래그가 켜는 것과 보장하는 것
* [사용 가능한 확장 기능](https://villagesql.com/docs/ko/extensions/catalog) — 전체 카탈로그
* [villagesql/vsql-mcp](https://github.com/villagesql/vsql-mcp) — 소스, 클라이언트 설정, 알려진 제한 사항


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.