MCP 클라이언트 설정 창은 Claude Code 같은 외부 AI 클라이언트가 NeoSQL MCP 서버(neosql-mcp)를 실행하도록 클라이언트의 설정 파일에 넣을 내용을 만들고, 원하면 설정 파일에 바로 등록합니다. MCP 가 무엇이고 외부 AI 가 무엇을 할 수 있는지, 어떤 안전장치가 걸리는지는 AI 와 MCP 에서 설명합니다.
사용할 수 있는 곳웹데스크톱로그인 없이로그인로컬 프로젝트계정 프로젝트
화면 구성
| 번호 | 이름 | 설명 |
|---|---|---|
| 1 | 설정 범위 | 전역 범위는 어느 폴더에서 클라이언트를 실행해도 NeoSQL MCP 를 사용하고, 작업할 프로젝트는 그때그때 NeoSQL 에서 선택합니다. 작업 디렉토리 범위는 설정 파일을 둔 폴더 아래에서 실행할 때만 사용하고, 설정 창을 연 프로젝트로 대상이 고정됩니다. 처음에는 전역 범위입니다. |
| 2 | 설치 권고 위치 | 선택한 클라이언트와 범위의 설정 파일이 놓일 자리입니다. 아래 표와 같습니다. |
| 3 | 주 용도 | 선택한 범위가 어떻게 동작하는지의 짧은 설명입니다. |
| 4 | 클라이언트 | 설정을 만들 클라이언트입니다. Claude Code, Codex, Gemini, Cursor, VS Code 가운데 선택합니다. 처음에는 Claude Code 입니다. Claude Code 를 선택하면 아래에 Claude Code(터미널)용 설정입니다. Claude 데스크톱 앱의 Cowork 는 Claude 플러그인으로 설치하세요. 안내가 보입니다. NeoSQLEnterprise 에서는 Claude Code(터미널)용 설정입니다. Claude 플러그인은 NeoSQLEnterprise 에 연결하지 않습니다. 안내가 보입니다. |
| 5 | 미리보기와 복사 버튼 | 설정 파일에 넣을 내용과 파일 이름입니다. 버튼을 클릭하면 내용이 클립보드에 복사됩니다. |
| 6 | 전역 등록 버튼 | 선택한 클라이언트의 전역 설정 파일에 NeoSQL MCP 를 바로 등록합니다. 전역 범위에서만 보입니다. |
| 7 | 다운로드 버튼 | 미리보기 내용을 파일로 저장합니다. 저장할 곳은 운영체제의 저장 창에서 선택합니다. |
- AI 설정 창에서 사용 항목을 활성화한 커넥션이 하나도 없으면 창 위에 MCP 접근이 허용된 Connection이 없습니다. 먼저 AI 설정에서 Connection의 ‘사용’을 켜세요. 경고가 나옵니다. 설정은 만들 수 있지만, 외부 AI 가 사용할 수 있는 커넥션이 없습니다.
- 만들어지는 설정은 클라이언트가
npx -y neosql-mcp를 실행하게 합니다. 작업 디렉토리 범위는 여기에--project-id=<프로젝트 ID>를 덧붙입니다. 계정이나 DB 의 비밀번호는 들어가지 않습니다. - NeoSQLEnterprise 가 만드는 설정은
npx대신 NeoSQLEnterprise 앱의 실행 파일로 앱에 든 MCP 서버를 실행하게 하고,ELECTRON_RUN_AS_NODE환경 변수와--profile=enterprise인자를 넣습니다. 자세한 내용은 MCP 설치와 연결 에서 설명합니다.
클라이언트마다 설정 파일의 모양과 자리가 다릅니다. ~ 는 사용자 홈 폴더입니다.
| 클라이언트 | 미리보기 파일 이름 | 전역 범위(전역 설정 파일) | 작업 디렉토리 범위 |
|---|---|---|---|
| Claude Code | 전역 범위 .claude.json, 작업 폴더 범위 .mcp.json | ~/.claude.json | <작업 폴더>/.mcp.json |
| Codex | config.toml | ~/.codex/config.toml. CODEX_HOME 이 있으면 CODEX_HOME 폴더 아래 | <작업 폴더>/.codex/config.toml |
| Gemini(Gemini CLI) | settings.json | ~/.gemini/settings.json. GEMINI_CLI_HOME 이 있으면 GEMINI_CLI_HOME 폴더 아래 | <작업 폴더>/.gemini/settings.json |
| Cursor | mcp.json | ~/.cursor/mcp.json | <작업 폴더>/.cursor/mcp.json |
| VS Code | mcp.json | macOS 는 ~/Library/Application Support/Code/User/mcp.json, Windows 는 %APPDATA%\Code\User\mcp.json | <작업 폴더>/.vscode/mcp.json |
창 열기
- 데스크톱 앱에서 프로젝트를 엽니다. 로그인하지 않았으면 로컬 프로젝트만 열 수 있습니다.
- 프로젝트 화면 위쪽의 AI 설정 버튼을 클릭합니다. 커넥션마다 AI, MCP 정책을 정하는 창이 열립니다 (프로젝트 AI 설정).
- 외부 AI 가 사용할 커넥션의 사용 항목을 활성화하고, 대상을 적지 않은 호출이 사용할 커넥션의 기본 항목을 선택한 뒤 저장 버튼을 클릭합니다.
- 창이 닫히면 AI 설정 버튼을 다시 클릭하고, 표 아래의 MCP 클라이언트 설정 버튼을 클릭합니다.
전역으로 등록하기
어느 폴더에서 작업하든 NeoSQL MCP 를 사용하려면 전역 등록이 가장 간단합니다.
설정 범위 칸에서 전역 항목을 선택하고, 사용하는 클라이언트를 선택합니다.
전역 등록 버튼을 클릭합니다. NeoSQL 이 선택한 클라이언트의 전역 설정 파일을 읽어 보고 확인 창을 띄웁니다.
확인 창에서 수정할 파일의 경로와 넣을 내용을 확인하고 버튼을 클릭합니다. 버튼은 상황에 따라 다릅니다.
상황 버튼 하는 일 설정 파일이 있고 NeoSQL 항목이 없음 등록 NeoSQL 항목만 더하고 다른 설정은 그대로 둡니다 설정 파일에 NeoSQL 항목이 이미 있음 교체 NeoSQL 항목만 새 내용으로 변경합니다 설정 파일이 없음 생성 설정 파일을 새로 만듭니다 NeoSQL MCP 설정을 등록했습니다. 알림이 표시되면 끝입니다. 클라이언트가 이미 실행 중이면 다시 시작하세요.
- 설정 파일을 해석하지 못하거나(형식이 깨진 JSON, TOML) 읽고 저장할 권한이 없으면 파일을 수정하지 않고 오류를 알립니다.
- 파일은 임시 파일에 저장한 뒤 교체하므로, 저장하는 도중 실패해도 원래 파일이 남습니다. 원래대로 되돌리는 데도 실패하면 같은 폴더의
<설정 파일>.neosql-mcp.backup백업 파일을 남기고 경로를 알립니다.
작업 폴더에 설정 파일 두기
한 저장소에서만 NeoSQL MCP 를 사용하거나, 늘 설정 창을 연 프로젝트를 대상으로 하게 하려면 작업 폴더에 설정 파일을 둡니다.
- 설정 범위 칸에서 작업 디렉토리 항목을 선택하고, 클라이언트를 선택합니다.
- 다운로드 버튼을 클릭하고, 저장 창에서 작업 폴더 아래 설치 권고 위치 칸의 자리를 선택합니다. 파일 이름에는 미리보기의 이름이 자동 기입되어 있습니다. 같은 이름의 파일이 있으면 운영체제가 덮어쓸지 묻습니다.
- 이미 설정 파일이 있으면 복사 버튼으로 복사해 기존 파일의
neosql항목에 붙여 넣습니다.
- 작업 디렉토리 범위의 설정에는 설정 창을 연 프로젝트의 ID 가 들어갑니다. 설정으로 실행한 클라이언트는 다른 프로젝트를 대상으로 할 수 없고, 새 프로젝트를 만드는 도구(
create-project)도 거절됩니다. - 대상 프로젝트가 NeoSQL 에 열려 있지 않으면 도구를 호출할 때 NeoSQL 이 대상 프로젝트로 화면을 옮깁니다. 지금 화면에 저장하지 않은 변경이 있으면 옮기지 않고 도구 호출이 실패합니다.
- macOS 에서 이름이 점으로 시작하는 파일(
.mcp.json)을 저장하면 운영체제가 숨김 파일이 된다고 물을 수 있습니다.
연결 확인하기
- NeoSQL 데스크톱 앱을 실행해 둡니다. 종료되어 있으면 MCP 서버가 앱을 띄우고 최대 40초 동안 준비를 기다립니다.
- 외부 AI 클라이언트를 다시 시작하고, 클라이언트의 MCP 서버 목록에
neosql이 연결되어 있는지 확인합니다(Claude Code 는/mcp). - 대화창에서 "NeoSQL 프로젝트 목록을 보여 줘" 처럼 요청합니다. 클라이언트가
list-projects도구를 호출하고 NeoSQL 의 프로젝트 목록을 받으면 데스크톱 앱까지 연결된 것입니다.
ping도구는 클라이언트와 MCP 서버 사이만 확인하고 데스크톱 앱에는 묻지 않습니다. 앱까지의 연결은list-projects나list-connections로 확인하세요.- 연결된 뒤 외부 AI 가 할 수 있는 일(스키마 읽기, ERD 설계, SQL 실행, 코드 생성)과 도구마다 받는 값은 MCP 도구 에서 설명합니다.
- 외부 AI 가 보낸 SQL 은 커넥션의 보호 모드와 정책에 따라 NeoSQL 에 확인 창(스키마 변경은 MCP DDL 실행 확인 창, 데이터 변경은 MCP SQL 실행 확인 창)을 띄우고, 새 프로젝트를 만들 때는 MCP 프로젝트 생성 확인 창을 띄웁니다. 세 창은 NeoSQL 화면에 표시되므로 앱을 볼 수 있는 곳에서 사용하세요. 정책과 확인 창이 걸리는 조건은 AI 와 MCP 에서 설명합니다.
주의할 점
- 데스크톱 앱 전용입니다. MCP 서버는 같은 기기의 데스크톱 앱에 요청을 넘깁니다. 웹 앱에는 MCP 클라이언트 설정 버튼이 없습니다. 계정 프로젝트도 데스크톱 앱에서 열어야 MCP 로 다룰 수 있습니다.
- 로그인하지 않으면 로컬 프로젝트만 다룹니다. 계정 프로젝트를 대상으로 하면 데스크톱 앱에 로그인하라는 안내와 함께 실패합니다.
- 클라이언트를 실행하는 기기에 Node.js 20 이상이 있어야 하고, 클라이언트가
npx를 실행할 수 있어야 합니다. - 설정 창의 Claude Code 는 터미널에서 실행하는 Claude Code 용 설정입니다. Claude 데스크톱 앱의 Cowork 에서는 Claude 플러그인으로 설치합니다 (MCP 설치와 연결). NeoSQLEnterprise 는 Claude 플러그인 대신 이 설정 창에서 등록합니다.
- 외부 클라이언트가 도구를 자동으로 승인하도록 설정되어 있으면 묻지 않고 SQL 을 실행합니다. 변경되면 안 되는 DB 의 커넥션은 사용 항목을 비활성화하거나 쓰기 권한이 없는 DB 계정으로 연결하세요.
- 외부 AI 에게 전달한 스키마와 조회 결과는 클라이언트가 사용하는 모델 제공자로 갈 수 있습니다. NeoSQL 은 전달 이후를 통제하지 못합니다.
관련 화면
- MCP 설치와 연결: 설정 창 대신 Claude 플러그인이나 직접 설정으로 설치하는 방법입니다.
- AI 와 MCP: AI Assistant 와 MCP 의 차이, 커넥션 정책, MCP 의 안전장치입니다.
- 프로젝트 AI 설정: 커넥션마다 MCP 사용과 스키마 변경, 데이터 변경 정책을 정하는 창입니다.
- MCP 도구: 외부 AI 가 호출할 수 있는 도구와 받는 값입니다.
- 외부 AI 로 ERD 설계하기(MCP): 연결한 뒤 외부 AI 로 ERD 를 설계하고 DB 에 반영하는 순서입니다.