핵심 개념

AI 와 MCP

NeoSQL 에서 AI 를 사용하는 길은 두 가지입니다. NeoSQL 화면 안에서 AI 와 대화하는 AI Assistant 와, Claude Code 같은 외부 AI 도구가 NeoSQL 을 도구로 호출하는 MCP(Model Context Protocol) 입니다. 둘은 호출하는 방향이 반대라서 사용하는 키, 데이터가 가는 곳, 안전장치가 다릅니다. 둘이 함께 따르는 것은 커넥션마다 정하는 정책 하나입니다.

호출하는 방향이 반대입니다

AI AssistantMCP
누가 누구를 호출하나NeoSQL 이 AI 제공자의 모델을 호출합니다외부 AI 클라이언트가 NeoSQL 을 호출합니다. NeoSQL 은 모델을 호출하지 않습니다
대화하는 곳프로젝트 화면 오른쪽의 AI Assistant 패널. 프로젝트 레일AI Assistant 버튼이나 Ctrl+I(macOS 는 Cmd+I)로 엽니다외부 AI 클라이언트의 대화창(Claude, Codex, Gemini, Cursor, VS Code 등)
모델과 비용내가 등록한 API 키로 호출하고, 비용은 등록한 키에서 나갑니다외부 클라이언트가 정합니다
사용할 수 있는 곳웹, 데스크톱데스크톱만
로그인하지 않으면로컬 프로젝트에서 기기 키로 사용합니다로컬 프로젝트만 다룹니다
실행 전에 묻는 곳NeoSQL 화면(조회 승인, 실행 확인)외부 클라이언트의 도구 승인. NeoSQL 은 보호 모드, 정책에 걸리는 SQL 과 프로젝트 만들기만 직접 묻습니다

API 키는 두 종류입니다

AI Assistant 는 내가 등록한 API 키로 모델을 호출합니다. 키는 마이페이지제공자 및 API 키 화면에서 등록하고, 저장되는 곳에 따라 두 종류로 나뉩니다. 사용할 수 있는 AI 제공자는 OpenAI, Anthropic, Google, Ollama 입니다.

계정 키기기 키
저장되는 곳내 계정(NeoSQL 서버). 암호화되어 저장됩니다기기. OS 보안 저장소로 보호됩니다
등록할 수 있는 곳웹, 로그인한 데스크톱데스크톱
월 예산정할 수 있습니다없습니다
사용량이 기록되는 곳내 계정기기

대화창에서 선택할 수 있는 키는 환경과 로그인 상태로 정해지고, 프로젝트 종류와는 상관없습니다.

환경선택할 수 있는 키
웹계정 키. http 주소나 localhost, 사설 IP 주소를 사용하는 계정 키는 데스크톱에서만 선택할 수 있습니다
데스크톱, 로그인하지 않음기기 키
데스크톱, 로그인계정 키와 기기 키 모두. 로컬 프로젝트든 계정 프로젝트든 같습니다

따로 선택하지 않으면 기본 Key로 정한 키를 사용하고, 계정 키와 기기 키에 모두 기본 Key가 있으면 계정 키의 기본 Key가 먼저입니다.

컨텍스트는 이번 요청의 허용 목록입니다

  • 메시지를 보내려면 먼저 Database Schema 선택 버튼으로 Database, Schema 를 하나 이상 선택해야 합니다. 선택한 것이 이번 요청에서 AI 가 볼 수 있는 범위의 전부입니다. AI 의 도구는 선택하지 않은 커넥션에 접속하지 않고, 대화 중에 범위가 넓어지지도 않습니다.
  • 커넥션의 AI 설정에서 사용 항목을 비활성화한 커넥션은 선택할 수 없습니다. DB 접속 정보 없이 설계만 하는 커넥션도 AI Assistant 에서는 사용하지 않습니다.

AI 제공자로 넘어가는 것

넘어가는 것언제
질문, 최근 대화, NeoSQL 이 붙이는 기능별 지침메시지를 보낼 때마다
선택한 컨텍스트의 커넥션, Database, Schema 이름메시지를 보낼 때마다
테이블, 뷰 목록과 테이블의 컬럼, 키, 인덱스, 관계, 제약AI 가 도구로 조회할 때. 묻지 않고 조회합니다
쿼리 튜닝을 맡긴 SQL 과 추정 실행 계획쿼리 튜닝을 요청할 때
오류가 난 SQL, SQLSTATE, 오류 메시지SQL 오류를 AI 에게 물을 때
실제 행의 값(한 번에 최대 10행)AI 가 조회 SQL 을 실행할 때. 데이터 전송 허용 항목이 비활성화된 커넥션에서는 화면에 AI가 데이터베이스 조회를 요청했습니다. 카드가 표시되고, 승인해야 실행됩니다
  • 데이터 전송 허용 항목은 새 커넥션에서 처음부터 활성화되어 있습니다. 그래서 처음에는 묻지 않고 실제 행을 조회해 보냅니다. 실제 행을 보내기 전에 묻게 하려면 데이터 전송 허용 항목을 비활성화하세요. 승인 카드에서 이후 조회 자동 승인 항목을 선택하면 대화에서는 다시 묻지 않습니다.
  • 응답에 들어 있는 조회 SQL 카드는 응답이 끝나면 쿼리를 실행하는 서버가 DB 에서 자동으로 실행해 결과가 보입니다. 조회 결과는 AI 제공자로 보내지 않습니다.
  • 요청은 AI 제공자에 직접 보냅니다. 데스크톱은 기기의 로컬 서버에서, 웹은 NeoSQL 서버에서 나갑니다. Ollama 처럼 기기나 사내에서 실행하는 모델을 사용하면 요청은 모델의 주소로만 갑니다.
  • 계정 프로젝트에서는 민감정보로 지정한 컬럼을 현재 사용자의 역할에 따라 마스킹하고, 커넥션에서 민감정보 항상 마스킹 항목을 활성화하면 역할과 상관없이 마스킹합니다. 로컬 프로젝트에는 마스킹이 없습니다.
  • 대화 기록은 계정 프로젝트면 내 계정에, 로컬 프로젝트면 기기에 저장됩니다.

두 기능이 함께 따르는 커넥션 정책

프로젝트 화면 위쪽의 AI 설정 버튼을 클릭하면 커넥션마다 정책을 정하는 표가 열립니다. AI Assistant 와 MCP 가 정책 표를 함께 따르므로, AI Assistant 를 위해 활성화한 정책은 외부 MCP 에도 적용됩니다.

번호열AI AssistantMCP
1사용비활성화하면 커넥션을 컨텍스트로 선택할 수 없습니다비활성화하면 커넥션 목록에서 빠지고, 커넥션을 대상으로 한 도구 호출을 거절합니다
2기본새 대화를 시작할 때 처음 선택해 두는 컨텍스트입니다도구 호출이 대상을 적지 않았을 때 사용하는 대상입니다
3스키마 변경활성화하면 AI 가 만든 DDL 을 확인 없이 실행하고, 비활성화하면 실행 전에 확인합니다활성화하면 DDL 을 확인 없이 실행하고, 비활성화하면 NeoSQL 에 확인 창을 띄웁니다
4데이터 변경활성화하면 AI 가 만든 INSERT, UPDATE, DELETE 를 확인 없이 실행하고, 비활성화하면 실행 전에 확인합니다활성화하면 자동 커밋합니다. 비활성화하면 트랜잭션을 열어 둔 채 돌려주고, NeoSQL 의 SQL 편집기 탭에서 커밋하거나 롤백합니다
5데이터 전송 허용활성화하면 실제 행을 조회할 때 묻지 않습니다사용하지 않습니다
6민감정보 항상 마스킹활성화하면 역할과 상관없이 민감정보를 가립니다. 계정 프로젝트에서만 사용할 수 있습니다AI Assistant 와 같습니다
  • 정책 표보다 앞서는 것이 있습니다. 커넥션 보호 모드가 읽기 전용 (SELECT 외 차단) 항목이면 AI Assistant 는 SELECT 가 아닌 문장을 실행하지 않고, 확인 (DDL + 위험 DML) 항목이면 정책과 상관없이 확인합니다. 계정 프로젝트에서 DDL 제한 권한이 걸린 사용자는 AI 로도 DDL 을 실행하지 못합니다.
  • 정책은 커넥션마다 정합니다. 공개 커넥션은 프로젝트 소유자가, 개인 커넥션은 만든 사람이, 로컬 프로젝트는 기기의 사용자가 변경합니다.
  • 설계 전용 표시가 붙은 커넥션은 DB 접속 정보가 없는 커넥션입니다. 외부 MCP 에서 execute-query 는 사용할 수 없고, 스키마 읽기, ERD 설계, 코드 생성 도구는 사용합니다. 실행 정책 칸은 사용하지 않습니다.
  • AI Assistant 도 대화로 ERD 의 테이블을 만들거나 수정할 수 있습니다. ERD 를 만들거나 수정하는 도구는 ERD 에만 저장하고 DB 는 변경하지 않습니다.

MCP 의 안전장치

  • 데스크톱 전용입니다. MCP 서버(neosql-mcp)는 외부 AI 클라이언트가 같은 기기에서 실행하는 프로그램이고, 기기 안의 통로로 데스크톱 앱에 요청을 넘깁니다. 실제 작업은 데스크톱 앱이 가진 프로젝트와 커넥션으로 합니다. 앱이 종료되어 있으면 MCP 서버가 앱을 띄우고 준비될 때까지 최대 40초 기다립니다. MCP 는 데스크톱 앱에서 사용합니다.
  • 로그인하지 않으면 로컬 프로젝트만 다룹니다. 계정 프로젝트는 데스크톱 앱에서 로그인해야 다룰 수 있습니다.
  • 외부 클라이언트에 넣을 설정은 AI 설정 창의 MCP 클라이언트 설정 버튼(7)으로 만듭니다. 데스크톱에서만 지원합니다.

MCP 가 호출할 수 있는 도구는 아래와 같습니다. 도구마다 받는 값과 돌려주는 값은 MCP 도구 에서 설명합니다.

하는 일도구
연결 확인과 안내ping, get-mcp-session-id, get-context-help
프로젝트list-projects, create-project
스키마 읽기list-connections, list-tables, get-table-details
ERD 설계(DB 는 그대로)erd-create-tables, erd-modify-tables
SQL 실행execute-query
코드 생성generate-code
  • ERD 도구는 DB 를 변경하지 않습니다. erd-create-tables 와 erd-modify-tables 는 ERD 에 가상 테이블과 변경을 저장할 뿐입니다. 결과는 MCP 세션과 위치(커넥션, Database, Schema)마다 생기는 ERD 탭에 보입니다. DB 에 반영하려면 NeoSQL 에서 DB 반영을 하거나(ERD 와 실제 DB), 외부 AI 가 execute-query 로 DDL 을 보내야 합니다.
  • execute-query 는 문장마다 확인 절차를 거칩니다. 위에서부터 처음 맞는 줄을 따르고, 여러 문장 중 하나라도 거절되면 아무것도 실행하지 않습니다.
순서조건결과
1DDL 이고, 계정 프로젝트에서 DDL 제한 권한이 걸린 사용자실행하지 않고 거절합니다
2커넥션 보호 모드가 읽기 전용 (SELECT 외 차단) 항목이고 조회가 아닌 문장(INSERT, UPDATE, DELETE, DDL 등)실행하지 않고 거절합니다
3보호 모드가 확인 (DDL + 위험 DML) 항목이고 DDL 이거나 조건 없는 UPDATE, DELETE, 또는 DDL 인데 스키마 변경 항목이 비활성화되어 있음NeoSQL 에 확인 창을 띄우고, 사용자가 실행을 클릭해야 실행합니다. 45초 안에 답이 없으면 실행하지 않습니다
4그 밖바로 실행합니다
  • 거절하면 외부 AI 에게 실행되지 않았다는 것과 다시 시도하지 말라는 안내를 돌려주고, 설정 때문에 거절한 경우에는 NeoSQL 화면에도 알립니다.
  • 확인 절차를 통과한 INSERT, UPDATE, DELETE 는 데이터 변경 항목이 자동 커밋 여부를 정하고, SQL 은 NeoSQL 의 SQL 편집기 탭에 남습니다. 조회 결과는 최대 200행까지 돌려줍니다(플랜의 행 수 제한이 더 작으면 그 값).
  • create-project 는 NeoSQL 에 확인 창을 띄우고, 사용자가 동의해야 프로젝트를 만듭니다. generate-code 는 따로 묻지 않고 파일을 저장하며, 기존 파일을 덮어쓸 수 있습니다.
  • 돌려준 데이터는 외부 클라이언트의 모델로 갑니다. MCP 로 돌려준 스키마와 조회 결과는 외부 AI 클라이언트로 넘어가고, 클라이언트가 사용하는 모델 제공자에게 보내질 수 있습니다. NeoSQL 은 그 이후를 통제하지 못합니다. 계정 프로젝트에서는 역할에 따른 마스킹과 민감정보 항상 마스킹 항목이 MCP 의 결과에도 적용됩니다.
  • 승인은 외부 클라이언트가 합니다. 외부 클라이언트가 도구를 자동으로 승인하도록 설정되어 있으면 사용자 확인 없이 호출이 들어옵니다. NeoSQL 쪽의 방어선은 위의 커넥션 정책과 실행 확인 절차입니다.

주의할 점

  • AI 가 만든 SQL 은 실행하기 전에 확인하세요. 운영 DB 의 커넥션에서는 스키마 변경 항목과 데이터 변경 항목을 활성화하지 않는 편이 안전합니다.
  • MCP 를 사용하는 동안에는 NeoSQL 데스크톱 앱이 실행되어 있어야 합니다. 앱을 닫으면 외부 클라이언트의 도구 호출은 처리되지 않습니다.
  • MCP 경로에서는 NeoSQL 이 모델을 호출하지 않으므로, NeoSQL 의 AI 사용량과 예산에 기록되지 않습니다.

관련 페이지