화면: AI, MCP 와 보안

MCP 클라이언트 설정

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
Codexconfig.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
Cursormcp.json~/.cursor/mcp.json<작업 폴더>/.cursor/mcp.json
VS Codemcp.jsonmacOS 는 ~/Library/Application Support/Code/User/mcp.json, Windows 는 %APPDATA%\Code\User\mcp.json<작업 폴더>/.vscode/mcp.json

창 열기

  1. 데스크톱 앱에서 프로젝트를 엽니다. 로그인하지 않았으면 로컬 프로젝트만 열 수 있습니다.
  2. 프로젝트 화면 위쪽의 AI 설정 버튼을 클릭합니다. 커넥션마다 AI, MCP 정책을 정하는 창이 열립니다 (프로젝트 AI 설정).
  3. 외부 AI 가 사용할 커넥션의 사용 항목을 활성화하고, 대상을 적지 않은 호출이 사용할 커넥션의 기본 항목을 선택한 뒤 저장 버튼을 클릭합니다.
  4. 창이 닫히면 AI 설정 버튼을 다시 클릭하고, 표 아래의 MCP 클라이언트 설정 버튼을 클릭합니다.

전역으로 등록하기

어느 폴더에서 작업하든 NeoSQL MCP 를 사용하려면 전역 등록이 가장 간단합니다.

  1. 설정 범위 칸에서 전역 항목을 선택하고, 사용하는 클라이언트를 선택합니다.

  2. 전역 등록 버튼을 클릭합니다. NeoSQL 이 선택한 클라이언트의 전역 설정 파일을 읽어 보고 확인 창을 띄웁니다.

  3. 확인 창에서 수정할 파일의 경로와 넣을 내용을 확인하고 버튼을 클릭합니다. 버튼은 상황에 따라 다릅니다.

    상황버튼하는 일
    설정 파일이 있고 NeoSQL 항목이 없음등록NeoSQL 항목만 더하고 다른 설정은 그대로 둡니다
    설정 파일에 NeoSQL 항목이 이미 있음교체NeoSQL 항목만 새 내용으로 변경합니다
    설정 파일이 없음생성설정 파일을 새로 만듭니다
  4. NeoSQL MCP 설정을 등록했습니다. 알림이 표시되면 끝입니다. 클라이언트가 이미 실행 중이면 다시 시작하세요.

  • 설정 파일을 해석하지 못하거나(형식이 깨진 JSON, TOML) 읽고 저장할 권한이 없으면 파일을 수정하지 않고 오류를 알립니다.
  • 파일은 임시 파일에 저장한 뒤 교체하므로, 저장하는 도중 실패해도 원래 파일이 남습니다. 원래대로 되돌리는 데도 실패하면 같은 폴더의 <설정 파일>.neosql-mcp.backup 백업 파일을 남기고 경로를 알립니다.

작업 폴더에 설정 파일 두기

한 저장소에서만 NeoSQL MCP 를 사용하거나, 늘 설정 창을 연 프로젝트를 대상으로 하게 하려면 작업 폴더에 설정 파일을 둡니다.

  1. 설정 범위 칸에서 작업 디렉토리 항목을 선택하고, 클라이언트를 선택합니다.
  2. 다운로드 버튼을 클릭하고, 저장 창에서 작업 폴더 아래 설치 권고 위치 칸의 자리를 선택합니다. 파일 이름에는 미리보기의 이름이 자동 기입되어 있습니다. 같은 이름의 파일이 있으면 운영체제가 덮어쓸지 묻습니다.
  3. 이미 설정 파일이 있으면 복사 버튼으로 복사해 기존 파일의 neosql 항목에 붙여 넣습니다.
  • 작업 디렉토리 범위의 설정에는 설정 창을 연 프로젝트의 ID 가 들어갑니다. 설정으로 실행한 클라이언트는 다른 프로젝트를 대상으로 할 수 없고, 새 프로젝트를 만드는 도구(create-project)도 거절됩니다.
  • 대상 프로젝트가 NeoSQL 에 열려 있지 않으면 도구를 호출할 때 NeoSQL 이 대상 프로젝트로 화면을 옮깁니다. 지금 화면에 저장하지 않은 변경이 있으면 옮기지 않고 도구 호출이 실패합니다.
  • macOS 에서 이름이 점으로 시작하는 파일(.mcp.json)을 저장하면 운영체제가 숨김 파일이 된다고 물을 수 있습니다.

연결 확인하기

  1. NeoSQL 데스크톱 앱을 실행해 둡니다. 종료되어 있으면 MCP 서버가 앱을 띄우고 최대 40초 동안 준비를 기다립니다.
  2. 외부 AI 클라이언트를 다시 시작하고, 클라이언트의 MCP 서버 목록에 neosql 이 연결되어 있는지 확인합니다(Claude Code 는 /mcp).
  3. 대화창에서 "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 에 반영하는 순서입니다.