참고

MCP 도구

NeoSQL MCP 서버(neosql-mcp)가 Claude Code 같은 외부 AI 클라이언트에 내놓는 도구는 12개입니다. 도구마다 하는 일, 받는 값, DB 나 파일을 변경하는지, NeoSQL 이 따로 묻는지를 표로 모았습니다. MCP 가 무엇이고 어떤 안전장치가 걸리는지는 AI 와 MCP, 클라이언트에 등록하는 방법은 MCP 클라이언트 설정 에서 설명합니다.

도구 한눈에 보기

도구하는 일변경하는 것NeoSQL 이 묻는 것
ping연결 확인. pong 을 돌려줍니다없음없음
get-mcp-session-idMCP 세션의 ID 를 돌려줍니다없음없음
get-context-help대상 프로젝트와 커넥션을 정하는 규칙을 안내합니다없음없음
list-projects기기에서 열 수 있는 프로젝트 목록없음없음
create-project새 로컬 프로젝트를 만듭니다프로젝트만들기 확인 창
list-connectionsAI 를 허용한 커넥션과 스키마 목록없음없음
list-tables테이블 목록(이름, 설명으로 찾기)없음없음
get-table-details테이블의 컬럼, 인덱스, 외래 키, 제약없음없음
erd-create-tablesERD 에 새 테이블을 설계합니다ERD(DB 는 그대로)없음
erd-modify-tablesERD 의 테이블을 수정합니다ERD(DB 는 그대로)없음
execute-querySQL 을 실행합니다DB보호 모드와 정책에 따라 실행 확인 창
generate-code프로젝트의 템플릿 팩으로 소스 파일을 만듭니다프로젝트 폴더의 파일없음

ping, get-mcp-session-id, get-context-help 는 MCP 서버 안에서 답하고 데스크톱 앱을 호출하지 않습니다. 나머지는 데스크톱 앱이 처리합니다.

대상을 정하는 인자

프로젝트와 DB 를 다루는 도구는 아래 인자를 함께 받습니다. 모두 생략할 수 있습니다.

인자받는 도구내용
projectIdlist-projects, create-project, ping 류를 제외한 도구대상 프로젝트. list-projects 나 create-project 가 돌려준 값입니다. 프로젝트가 열려 있지 않으면 데스크톱 앱이 엽니다
connectionId, database, schemalist-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테이블 설명 변경하기(생략 가능)
primaryKeyOperationsPK 컬럼 더하기, 제외하기(생략 가능)
columnOperations컬럼 ADD, DROP, MODIFY, RENAME
indexOperations인덱스 ADD, DROP
foreignKeyOperations외래 키 ADD, DROP
constraintOperationsUNIQUE, 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 입니다.

순서조건결과
1DDL 이고, 계정 프로젝트에서 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 으로 관리하는 폴더에서 사용하고, 만든 뒤 변경을 확인하세요.
  • 돌려준 스키마와 조회 결과는 외부 클라이언트를 거쳐 클라이언트의 모델 제공자로 갈 수 있습니다.

관련 화면