NeoSQL MCP 서버(neosql-mcp)가 Claude Code 같은 외부 AI 클라이언트에 내놓는 도구는 12개입니다. 도구마다 하는 일, 받는 값, DB 나 파일을 변경하는지, NeoSQL 이 따로 묻는지를 표로 모았습니다. MCP 가 무엇이고 어떤 안전장치가 걸리는지는 AI 와 MCP, 클라이언트에 등록하는 방법은 MCP 클라이언트 설정 에서 설명합니다.
도구 한눈에 보기
| 도구 | 하는 일 | 변경하는 것 | NeoSQL 이 묻는 것 |
|---|---|---|---|
ping | 연결 확인. pong 을 돌려줍니다 | 없음 | 없음 |
get-mcp-session-id | MCP 세션의 ID 를 돌려줍니다 | 없음 | 없음 |
get-context-help | 대상 프로젝트와 커넥션을 정하는 규칙을 안내합니다 | 없음 | 없음 |
list-projects | 기기에서 열 수 있는 프로젝트 목록 | 없음 | 없음 |
create-project | 새 로컬 프로젝트를 만듭니다 | 프로젝트 | 만들기 확인 창 |
list-connections | AI 를 허용한 커넥션과 스키마 목록 | 없음 | 없음 |
list-tables | 테이블 목록(이름, 설명으로 찾기) | 없음 | 없음 |
get-table-details | 테이블의 컬럼, 인덱스, 외래 키, 제약 | 없음 | 없음 |
erd-create-tables | ERD 에 새 테이블을 설계합니다 | ERD(DB 는 그대로) | 없음 |
erd-modify-tables | ERD 의 테이블을 수정합니다 | ERD(DB 는 그대로) | 없음 |
execute-query | SQL 을 실행합니다 | DB | 보호 모드와 정책에 따라 실행 확인 창 |
generate-code | 프로젝트의 템플릿 팩으로 소스 파일을 만듭니다 | 프로젝트 폴더의 파일 | 없음 |
ping, get-mcp-session-id, get-context-help 는 MCP 서버 안에서 답하고 데스크톱 앱을 호출하지 않습니다. 나머지는 데스크톱 앱이 처리합니다.
대상을 정하는 인자
프로젝트와 DB 를 다루는 도구는 아래 인자를 함께 받습니다. 모두 생략할 수 있습니다.
| 인자 | 받는 도구 | 내용 |
|---|---|---|
projectId | list-projects, create-project, ping 류를 제외한 도구 | 대상 프로젝트. list-projects 나 create-project 가 돌려준 값입니다. 프로젝트가 열려 있지 않으면 데스크톱 앱이 엽니다 |
connectionId, database, schema | list-tables, get-table-details, erd-create-tables, erd-modify-tables, execute-query, generate-code | 대상 커넥션과 위치. 셋을 함께 주거나 모두 생략합니다. database 는 계층이 없는 DBMS 면 null 입니다 |
- 대상 프로젝트는
projectId인자, 클라이언트 설정의--project-id, 데스크톱 앱에 열린 프로젝트 순으로 정합니다. 설정에--project-id가 있는데 다른projectId를 주면 실행하지 않고 오류를 돌려줍니다. - 위치를 생략하면 프로젝트 AI 설정 에서 기본 항목으로 선택한 곳을 사용합니다. 선택한 곳이 없거나 여럿이면 오류입니다. 계정 프로젝트에서는 공개 커넥션의 기본이 개인 커넥션보다 먼저입니다.
- 사용 항목이 비활성화된 커넥션을 가리키면 거절합니다.
list-connections는 그런 커넥션을 목록에서 제외합니다.
연결과 안내
ping
인자가 없습니다. MCP 서버가 살아 있는지만 봅니다. 데스크톱 앱과 연결되었는지는 확인하지 않으므로, 앱까지 확인하려면 list-projects 를 호출합니다.
get-mcp-session-id
인자가 없습니다. MCP 서버가 표시될 때 만든 세션 ID 를 돌려줍니다. 세션 ID 로 MCP: 로 시작하는 SQL 편집기 탭과 ERD 가 세션마다 따로 생깁니다.
get-context-help
인자가 없습니다. 대상 프로젝트를 선택하는 순서, 위치 인자를 셋 함께 주는 규칙, 커넥션을 찾는 도구(list-connections), 클라이언트 설정 예 (npx -y neosql-mcp)를 돌려줍니다.
프로젝트
list-projects
인자가 없고, 열린 프로젝트가 없어도 됩니다. 프로젝트마다 projectId, 이름, 종류(local, account), 마지막으로 연 때, 지금 열려 있는지를 돌려줍니다. 로그인하지 않았으면 로컬 프로젝트만 나오고, 계정 프로젝트를 제외했다는 표시(signed_out)가 함께 옵니다. 사용이 중지된 프로젝트는 나오지 않습니다.
create-project
| 인자 | 내용 |
|---|---|
name | 프로젝트 이름. 앞뒤 공백을 삭제하고 100자까지 |
dataSource | 설계할 DBMS 이름(예: PostgreSQL, MySQL). 대소문자는 가리지 않습니다. 받지 않는 이름이면 받을 수 있는 이름 목록을 오류로 돌려줍니다 |
- 데스크톱 앱에 MCP 프로젝트 생성 확인 창이 표시되고, 사용자가 동의해야 만듭니다. 45초 안에 답이 없으면 만들지 않습니다.
- 만드는 것은 로컬 프로젝트 이고, DB 접속 정보 없이 설계만 하는 커넥션 하나가 기본 위치로 들어 있습니다. 로그인하지 않아도 됩니다.
- 열려 있는 프로젝트에 저장하지 않은 변경이 있으면 만들지 않습니다. 만들면 열려 있던 프로젝트를 닫고 새 프로젝트를 엽니다.
- 클라이언트 설정에
--project-id가 있으면(프로젝트 범위 설정) 사용할 수 없습니다.
스키마 읽기
list-connections
인자는 projectId 뿐입니다. AI 를 허용했고 스키마를 하나 이상 선택한 커넥션마다 connectionId, 이름, 설명, DBMS 와 버전, 설계 전용 여부, 커넥션 프로필(환경과 보호 모드), 사용할 수 있는 Database, Schema 와 위치의 자동 커밋 여부를 돌려줍니다. DDL 을 묻지 않고 실행하는지는 알려 주지 않습니다.
list-tables
| 인자 | 내용 |
|---|---|
search | 테이블 이름이나 설명에 들어 있는 글자. 대소문자를 가리지 않습니다. 생략하면 모두 |
NeoSQL 이 이미 읽어 둔 목록에서 찾으므로 DB 에 SQL 을 보내지 않습니다. 테이블마다 이름, 종류, 설명을 돌려줍니다.
get-table-details
| 인자 | 내용 |
|---|---|
tableNames | 테이블 이름 목록(하나여도 목록). 대소문자까지 똑같이 적습니다 |
테이블마다 컬럼, 인덱스, 외래 키, 제약을 돌려주고, 찾지 못한 이름은 notFound 에 모읍니다. 아직 읽지 않은 테이블은 이때 DB 에서 메타데이터를 읽습니다.
ERD 설계
두 도구는 ERD 와 프로젝트의 설계에만 저장하고 DB 는 변경하지 않습니다. 결과는 MCP: 로 시작하는 ERD 탭에 보이고, ERD 는 MCP 세션과 위치(커넥션, Database, Schema)마다 하나씩 생깁니다. 설계 전용 커넥션에서도 사용할 수 있습니다. DB 에 반영하는 방법은 ERD 와 실제 DB 에서 설명합니다.
erd-create-tables
| 인자 | 내용 |
|---|---|
tableDefinitions | 만들 테이블 목록. 테이블마다 name, remarks, columns, primaryKeys, importedKeys(외래 키), indexes, constraints 를 모두 적습니다 |
컬럼마다 이름, 타입, size, decimalDigits, nullable, autoIncrement, defaultValue, remarks 를 적습니다. 이미 있는 이름의 테이블은 건너뜁니다.
erd-modify-tables
| 인자 | 내용 |
|---|---|
alterations | 수정할 테이블 목록. 테이블마다 tableName 과 아래 작업을 적습니다 |
| 작업 | 할 수 있는 일 |
|---|---|
newTableName | 테이블 이름 변경하기 |
remarksOperation | 테이블 설명 변경하기(생략 가능) |
primaryKeyOperations | PK 컬럼 더하기, 제외하기(생략 가능) |
columnOperations | 컬럼 ADD, DROP, MODIFY, RENAME |
indexOperations | 인덱스 ADD, DROP |
foreignKeyOperations | 외래 키 ADD, DROP |
constraintOperations | UNIQUE, CHECK, EXCLUSION 제약 ADD, DROP |
SQL 실행
execute-query
| 인자 | 내용 |
|---|---|
sql | 실행할 SQL |
- 설계 전용 커넥션에서는 사용할 수 없습니다.
- SQL 은 MCP 세션과 위치마다 생기는
MCP:SQL 편집기 탭에 남고, 탭에서 실행됩니다. - 조회 결과는 최대 200행입니다. 플랜의 행 수 제한이 더 작으면 제한 값을 따릅니다. 잘렸으면
truncated로 알립니다.
보내는 SQL 은 문장마다 아래 순서로 검사합니다. 위에서부터 처음 맞는 줄을 따르고, 여러 문장을 보냈으면 그중 하나라도 거절되면 아무것도 실행하지 않습니다. DDL 은 CREATE, ALTER, DROP, RENAME, TRUNCATE, COMMENT, GRANT, REVOKE, SELECT … INTO 입니다.
| 순서 | 조건 | 결과 |
|---|---|---|
| 1 | DDL 이고, 계정 프로젝트에서 DDL 제한 권한이 걸린 사용자 | 거절합니다 |
| 2 | 커넥션 보호 모드가 읽기 전용 (SELECT 외 차단) 항목이고, 조회(SELECT, 조회를 설명하는 EXPLAIN)가 아닌 문장 | 거절합니다 |
| 3 | 보호 모드가 확인 (DDL + 위험 DML) 항목이고 DDL 이거나 조건 없는 UPDATE, DELETE, 또는 DDL 인데 스키마 변경 항목이 비활성화 | NeoSQL 에 확인 창(MCP DDL 실행 확인 창 또는 MCP SQL 실행 확인 창)을 띄우고, 실행을 클릭해야 실행합니다. 45초 안에 답이 없으면 실행하지 않습니다 |
| 4 | 그 밖 | 바로 실행합니다 |
검사를 통과한 뒤의 커밋은 아래와 같습니다.
| 경우 | 결과 |
|---|---|
| 데이터 변경 항목이 활성화 | 자동 커밋합니다 |
| 데이터 변경 항목이 비활성화 | 트랜잭션을 열어 둔 채 돌려줍니다. NeoSQL 의 MCP: SQL 편집기 탭에서 커밋하거나 롤백합니다 |
| 열린 트랜잭션이 있는데 DDL 을 보냄 | 실행하지 않습니다. DDL 이 열린 트랜잭션을 확정해 버리기 때문입니다 |
조회 결과의 마스킹은 계정 프로젝트에만 있습니다. 민감정보로 지정한 컬럼을 사용자의 역할에 따라 마스킹하고, 커넥션에서 민감정보 항상 마스킹 항목을 활성화하면 역할과 상관없이 마스킹합니다. 마스킹한 컬럼은 결과에 따로 표시합니다. 마스킹 정보를 받지 못하면 실행하지 않습니다. 로컬 프로젝트에는 마스킹이 없습니다.
코드 생성
generate-code
| 인자 | 내용 |
|---|---|
tableNames | 코드를 만들 테이블 이름 목록(하나여도 목록) |
- 프로젝트에 넣은 템플릿 팩으로 파일을 만들어 프로젝트 폴더에 묻지 않고 저장합니다. 템플릿의 설치 설정에 따라 있던 파일을 덮어쓰거나 표시한 자리를 변경합니다. 만든 코드 대신 저장한 파일 경로, 건너뛴 것, 실패한 것을 돌려줍니다.
- 프로젝트 폴더(Location), 템플릿 팩, 반드시 기입할 변수가 없으면 파일을 만들지 않고
needs-configuration을 돌려줍니다. 기입하는 곳은 소스코드 생성 에서 설명합니다. - 템플릿에서 사용하는 값과 함수는 템플릿 문법 과 같습니다.
주의할 점
- 외부 클라이언트가 도구를 자동 승인하도록 설정되어 있으면 사용자 확인 없이 호출이 들어옵니다. NeoSQL 이 직접 묻는 것은
create-project와, 보호 모드와 정책에 따른execute-query뿐입니다. - 보호 모드가 없는 커넥션에서 데이터 변경 항목을 활성화해 두면 조건 없는 DELETE 도 묻지 않고 자동 커밋합니다. 운영 DB 는 보호 모드를 정하거나, 데이터를 변경할 권한이 없는 DB 계정으로 연결하세요.
generate-code는 묻지 않고 파일을 덮어쓸 수 있습니다. Git 으로 관리하는 폴더에서 사용하고, 만든 뒤 변경을 확인하세요.- 돌려준 스키마와 조회 결과는 외부 클라이언트를 거쳐 클라이언트의 모델 제공자로 갈 수 있습니다.
관련 화면
- AI 와 MCP: MCP 와 AI Assistant 의 차이, 커넥션 정책, DDL 실행 검사입니다.
- MCP 클라이언트 설정: 외부 AI 클라이언트에 NeoSQL MCP 를 등록하는 창입니다.
- 프로젝트 AI 설정: 커넥션마다 AI 를 어디까지 허용할지 정하는 창입니다.
- SQL 편집기:
MCP:탭에서 남은 SQL 을 보고 커밋하거나 롤백하는 화면입니다. - ERD 캔버스:
MCP:ERD 를 보고 다듬는 화면입니다. - 운영 DB 안전장치: 커넥션 보호 모드와 위험 SQL 확인입니다.
- 컬럼 마스킹: 민감정보 컬럼과 역할별 마스킹입니다.