Neo4j MCP Canary — 카나리아가 먼저 가서 나머지 우리가 무엇이 올지 알게 됩니다

Neo4j MCP Canary는 공식 서버에 반영되기 전에 새로 떠오르는 기능을 먼저 탐색하려는 고객을 위한 빠르게 진화하는 실험적 Neo4j MCP 서버 릴리스입니다.

Neo4j 공식 MCP(Model Context Protocol) 서버의 소스를 기반으로 하는 이 변형은 실험을 통해 새로운 잠재적 기능을 탐색하기 위한 것입니다.

랩스 프로젝트이므로 다음 사항에 유의하세요.

• 지원되지 않습니다.

• 자체 릴리스 간, 그리고 공식 Neo4j MCP 서버와의 사이에서 호환성이 깨지는 변경 사항이 포함될 수 있습니다.

• 사용 전에 테스트해야 합니다.

기여는 언제나 환영합니다. 특히 이 카나리아 채널에서는 새로운 아이디어에 항상 열려 있습니다.

카나리아가 사용자의 상황에서 작동할 것이라고 가정하지 마세요. 먼저 테스트하세요.

사전 요구 사항

• 실행 중인 Neo4j 데이터베이스 인스턴스. 옵션으로 Aura, Neo4j Desktop, 자체 관리가 있습니다.

• Neo4j 인스턴스에 APOC 플러그인 설치(필수 — get-schema는 apoc.meta.schema를 사용합니다).

• MCP 호환 클라이언트(예: MCP 지원이 포함된 VSCode).

⚠️ 알려진 문제: Neo4j 5.26.18에는 get-schema 도구를 실패하게 만드는 APOC 버그가 있습니다. 이 문제는 5.26.19 이상에서 수정되었습니다. 5.26.18을 사용 중이라면 업그레이드하세요. 자세한 내용은 #136을 참조하세요.

Related MCP server: FastMCP Production-Ready Server

시작 검사 및 적응형 작동

서버는 시작 시 환경이 올바르게 구성되었는지 확인하기 위해 여러 사전 점검을 수행합니다.

STDIO 모드 — 필수 요구 사항 STDIO 모드에서 서버는 다음을 확인합니다. 검사 중 하나라도 실패하면(예: 잘못된 구성, 잘못된 자격 증명, APOC 누락) 서버가 시작되지 않습니다.

• Neo4j 인스턴스에 대한 유효한 연결.

• 쿼리 실행 기능.

• APOC 플러그인의 존재.

HTTP 모드 — 검증 생략 HTTP 모드에서는 자격 증명이 요청별 인증 헤더에서 오기 때문에 시작 시 검증 검사를 건너뜁니다. 서버는 Neo4j에 연결하지 않고 즉시 시작됩니다. 유일한 예외는 Query API 모드입니다. 이 모드의 최소 버전 검사는 인증되지 않은 GET만 필요하고 요청별 자격 증명에 의존하지 않으므로 두 전송 모드 모두에서 시작 시 실행됩니다.

선택적 요구 사항 선택적 종속성이 누락된 경우 서버는 적응형 모드로 시작합니다. 예를 들어 Graph Data Science(GDS) 라이브러리가 감지되지 않으면 서버는 계속 시작되지만 list-gds-procedures와 같은 GDS 종속 도구는 자동으로 비활성화됩니다. 다른 모든 도구는 계속 사용할 수 있습니다.

설치(바이너리)

릴리스: https://github.com/neo4j-labs/neo4j-mcp-canary/releases

1. OS/아키텍처에 맞는 아카이브를 다운로드합니다.

2. 압축을 풀고 neo4j-mcp-canary를 PATH에 배치합니다.

Mac / Linux:

Mac에서는 바이너리를 처음 실행하려고 할 때 경고가 표시될 수 있습니다. 그런 경우 시스템 설정 → 개인정보 보호 및 보안에서 승인하세요.

chmod +x neo4j-mcp-canary
sudo mv neo4j-mcp-canary /usr/local/bin/

Windows(PowerShell / cmd):

move neo4j-mcp-canary.exe C:\Windows\System32

설치 확인:

neo4j-mcp-canary -v

설치된 버전이 출력되어야 합니다.

소스에서 빌드

Go 1.25.3+ 필요(go.mod 참조).

Task로 현재 플랫폼용으로 빌드:

task build

그러면 bin/neo4j-mcp-canary가 생성됩니다. Task가 없는 경우 동일한 작업은 다음과 같습니다:

go build -C cmd/neo4j-mcp -o ../../bin/

macOS / Linux용 크로스 컴파일

GOOS/GOARCH를 설정하고 cgo를 비활성화하여 크로스 컴파일합니다(코드베이스는 순수 Go이므로 CGO_ENABLED=0은 대상 머신에 런타임 종속성이 없는 완전한 정적 바이너리를 생성합니다):

CGO_ENABLED=0 GOOS=darwin  GOARCH=amd64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_darwin_amd64
CGO_ENABLED=0 GOOS=darwin  GOARCH=arm64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_darwin_arm64
CGO_ENABLED=0 GOOS=linux   GOARCH=amd64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_linux_amd64
CGO_ENABLED=0 GOOS=linux   GOARCH=arm64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_linux_arm64

바이너리에 버전을 각인하려면(-v / --version) ldflags 재정의를 전달하세요. 릴리스 파이프라인이 태그가 지정된 빌드에 대해 수행하는 작업입니다:

go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary \
  -ldflags "-X 'main.Version=$(git rev-parse --short HEAD)'"

이것이 없으면 Version은 "development"로 기본 설정되며, 이는 NEO4J_TELEMETRY와 관계없이 텔레메트리도 비활성화합니다(텔레메트리 참조).

공식 다중 플랫폼 릴리스 아카이브(Windows 포함)는 GoReleaser가 .goreleaser.yaml에 따라 빌드합니다. 로컬에서 빌드하는 대신 해당 아카이브를 다운로드하려면 설치(바이너리)를 참조하세요.

전송 모드

Neo4j MCP Canary 서버는 두 가지 전송 모드를 지원합니다:

• STDIO(기본값): 데스크톱 클라이언트(Claude Desktop, VSCode)를 위한 stdin/stdout을 통한 표준 MCP 통신.

• HTTP: 웹 기반 클라이언트 및 다중 테넌트 시나리오를 위한 요청별 Bearer 토큰 또는 Basic Authentication이 있는 RESTful HTTP 서버. 표준 Authorization 헤더를 사용할 수 없는 경우 사용자 지정 헤더 이름을 구성할 수 있습니다.

주요 차이점

두 모드의 구성 지침은 클라이언트 설정 가이드를 참조하세요.

인증되지 않은 MCP 클라이언트 요청

기본적으로 MCP 클라이언트가 HTTP(S) 전송을 사용할 때 인증 없이 보낼 수 있는 요청은 네 가지입니다. 일부 통합(AWS AgentCore, AWS Gateway 등)은 이를 초기 상태 확인 메커니즘으로 사용합니다:

• ping

• initialize

• tools/list

• notifications/initialize

이러한 요청이 필요하지 않으면 아래 변수를 통해 개별적으로 인증을 적용하세요.

TLS/HTTPS 구성

HTTP 전송을 사용할 때 아래 변수를 통해 보안 통신을 위한 TLS를 활성화하세요.

보안 구성

• 최소 TLS 버전: TLS 1.2(사용 가능한 경우 TLS 1.3 협상)

• 암호화 스위트: Go의 보안 기본 암호화 스위트

• 기본 포트: TLS가 활성화된 경우 자동으로 443 사용

예시

export NEO4J_URI="bolt://localhost:7687"
export NEO4J_TRANSPORT_MODE="http"
export NEO4J_MCP_HTTP_TLS_ENABLED="true"
export NEO4J_MCP_HTTP_TLS_CERT_FILE="/path/to/cert.pem"
export NEO4J_MCP_HTTP_TLS_KEY_FILE="/path/to/key.pem"

neo4j-mcp-canary
# Server listens on https://127.0.0.1:443 by default

프로덕션 사용: 프로덕션 배포에는 신뢰할 수 있는 CA(Let's Encrypt, 조직의 CA 등)의 인증서를 사용하세요.

인증서 생성, TLS 테스트 및 프로덕션 배포에 대한 자세한 지침은 CONTRIBUTING.md를 참조하세요.

구성 옵션

neo4j-mcp-canary 서버는 환경 변수, CLI 플래그 및/또는 선택적 구성 파일을 통해 구성됩니다. CLI 플래그는 환경 변수보다 우선하며, 환경 변수는 선택적 구성 파일보다 우선합니다.

환경 변수

핵심 연결 및 동작:

Bolt 대신 Query API를 통한 연결

NEO4J_URI의 스키마는 서버가 Neo4j와 통신하는 데 사용하는 와이어 프로토콜을 결정합니다. 별도의 플래그가 필요하지 않습니다:

• bolt://, bolt+s://, neo4j://, neo4j+s:// 등 → Bolt 드라이버(기본값, 동작 변경 없음).

• http:// 또는 https:// → Neo4j Query API, Neo4j의 HTTP 기반 쿼리 인터페이스. HTTP만 노출하거나 Bolt 사용을 선호하지 않는 배포에 유용합니다.

Query API 모드에는 Neo4j 2026.07 이상(캘린더 버전 릴리스) 또는 5.27-aura 이상(클래식 버전 Aura 릴리스 전용 — -aura 접미사가 없는 일반 클래식 버전은 지원되지 않음)이 필요합니다. 이 최소 버전은 Query API 자체의 GA(일반 공급) 시점(2026.06)보다 한 릴리스 뒤입니다. read-cypher의 쓰기 쿼리 거부는 쿼리 응답의 queryType 필드에 의존하는데, Neo4j가 이 필드를 도입한 것은 2026.07부터이기 때문입니다. 2026.06 서버에는 쿼리를 실행하기 전에 읽기 전용으로 분류할 신뢰할 수 있는 신호가 없습니다. 서버는 시작 시 연결된 인스턴스가 보고하는 버전을 이 최소 버전과 대조하고(기본 URI에 대한 인증 없는 GET을 통해), 너무 오래된 경우 발견한 버전과 최소 요구 버전을 명시하는 오류와 함께 시작을 거부합니다.

NEO4J_USERNAME/NEO4J_PASSWORD 및 요청별 Basic/Bearer 자격 증명은 Query API 모드에서 Bolt와 동일하게 작동합니다. 전송 모드 및 인증 방법 (HTTP 모드)를 참조하세요.

Cypher 실행 안전장치(Cypher 실행 안전장치 참조):

HTTP 전송, TLS 및 인증(위 표 참조).

CLI 플래그

CLI 플래그를 사용하여 모든 환경 변수를 재정의할 수 있습니다:

neo4j-mcp-canary \
  --neo4j-uri "bolt://localhost:7687" \
  --neo4j-username "neo4j" \
  --neo4j-password "password" \
  --neo4j-database "neo4j" \
  --neo4j-read-only false \
  --neo4j-telemetry true

사용 가능한 플래그:

연결 및 동작

• --neo4j-uri — NEO4J_URI 재정의

• --neo4j-username — NEO4J_USERNAME 재정의

• --neo4j-password — NEO4J_PASSWORD 재정의

• --neo4j-database — NEO4J_DATABASE 재정의

• --neo4j-read-only — NEO4J_READ_ONLY 재정의 (true / false)

• --neo4j-telemetry — NEO4J_TELEMETRY 재정의 (true / false)

• --neo4j-schema-sample-size — NEO4J_SCHEMA_SAMPLE_SIZE 재정의

• --neo4j-output-format — NEO4J_OUTPUT_FORMAT 재정의 (json / toon)

Cypher 실행 안전장치

• --neo4j-cypher-max-rows — NEO4J_CYPHER_MAX_ROWS 재정의 (0이면 비활성화)

• --neo4j-cypher-max-bytes — NEO4J_CYPHER_MAX_BYTES 재정의 (0이면 비활성화)

• --neo4j-cypher-timeout — NEO4J_CYPHER_TIMEOUT 재정의 (초; 0이면 비활성화)

• --neo4j-cypher-max-estimated-rows — NEO4J_CYPHER_MAX_ESTIMATED_ROWS 재정의 (0이면 비활성화)

전송 / HTTP

• --neo4j-transport-mode — stdio 또는 http

• --neo4j-http-host — NEO4J_MCP_HTTP_HOST 재정의

• --neo4j-http-port — NEO4J_MCP_HTTP_PORT 재정의

• --neo4j-http-allowed-origins — NEO4J_MCP_HTTP_ALLOWED_ORIGINS 재정의 (쉼표로 구분된 CORS 출처)

• --neo4j-http-tls-enabled — NEO4J_MCP_HTTP_TLS_ENABLED 재정의

• --neo4j-http-tls-cert-file — NEO4J_MCP_HTTP_TLS_CERT_FILE 재정의

• --neo4j-http-tls-key-file — NEO4J_MCP_HTTP_TLS_KEY_FILE 재정의

• --neo4j-http-auth-header-name — NEO4J_HTTP_AUTH_HEADER_NAME 재정의

• --neo4j-http-allow-unauthenticated-ping — NEO4J_HTTP_ALLOW_UNAUTHENTICATED_PING 재정의

• --neo4j-http-allow-unauthenticated-tools-list — NEO4J_HTTP_ALLOW_UNAUTHENTICATED_TOOLS_LIST 재정의

• --neo4j-http-allow-unauthenticated-initialize — NEO4J_HTTP_ALLOW_UNAUTHENTICATED_INITIALIZE 재정의

• --neo4j-http-allow-unauthenticated-notifications-initialize — NEO4J_HTTP_ALLOW_UNAUTHENTICATED_NOTIFICATIONS_INITIALIZE 재정의

전체 목록과 설명을 보려면 neo4j-mcp-canary --help를 실행하세요.

구성 파일

환경 변수에 대한 가장 낮은 우선순위의 대안으로, neo4j-mcp-canary는 선택적 JSON 또는 YAML 파일에서 구성을 읽을 수 있습니다:

neo4j-mcp-canary --config-file /etc/neo4j-mcp/config.yaml
# or
NEO4J_CONFIG_FILE=/etc/neo4j-mcp/config.yaml neo4j-mcp-canary

키는 해당 환경 변수 이름을 소문자로 바꾼 형태입니다:

neo4j_uri: bolt://localhost:7687
neo4j_username: neo4j
neo4j_password: password
neo4j_read_only: false
neo4j_transport_mode: http
neo4j_http_tls_enabled: true
neo4j_cypher_max_rows: 500

동일한 JSON도 허용됩니다(.json 확장자). 스칼라 값(문자열, 숫자, 불리언)만 지원되며, 중첩된 객체나 목록은 시작 오류입니다. CLI 플래그나 환경 변수의 값은 항상 구성 파일보다 우선합니다. 읽거나 구문 분석에 실패한 --config-file은 시작 오류입니다.

서버에 새 구성 매개변수를 추가하려면(환경 변수 + CLI 플래그 + 구성 파일 키를 한 번에) internal/config/schema.go의 fields 슬라이스에 항목 하나를 추가하면 됩니다. 형태에 대해서는 해당 파일의 doc 주석을 참조하세요.

응답 형식 (JSON vs TOON)

도구 응답(read-cypher, write-cypher, get-schema, list-gds-procedures)은 기본적으로 JSON으로 렌더링됩니다. NEO4J_OUTPUT_FORMAT(또는 --neo4j-output-format)을 toon으로 설정하면 대신 TOON(Token-Oriented Object Notation)으로 렌더링됩니다. 이는 JSON에 비해 LLM 토큰 사용량을 줄여주는 간결하면서도 사람이 읽을 수 있는 형식으로, 특히 이 도구들이 반환하는 표 형태의 행 구조에 유용합니다:

neo4j-mcp-canary --neo4j-output-format toon
# or
NEO4J_OUTPUT_FORMAT=toon neo4j-mcp-canary

read-cypher 결과를 JSON으로 표시:

{
  "rows": [
    { "name": "Alice", "age": 30 },
    { "name": "Bob", "age": 25 }
  ],
  "rowCount": 2,
  "truncated": false
}

동일한 결과를 TOON으로 표시:

rowCount: 2
rows[2]{age,name}:
  30,Alice
  25,Bob
truncated: false

잘못된 값은 NEO4J_LOG_FORMAT과 동일하게 stderr에 경고를 출력하고 json으로 대체됩니다.

Cypher 실행 안전장치

read-cypher와 write-cypher는 네 가지 계층형 안전장치로 보호되며, 이들이 함께 과도하게 적극적인 LLM이 MCP 전송을 중단시키거나 데이터베이스를 고갈시키는 것을 방지합니다. 각 계층은 서로 다른 실패 모드를 포착하며, 함께 심층 방어 역할을 합니다.

특정 계층을 비활성화하려면 해당 값을 0으로 설정하세요.

잘림 봉투

행 상한이나 바이트 상한 중 하나가 발동하면 도구는 이미 수집한 행과 함께 잘림 봉투를 반환합니다:

{
  "rows": [ /* ... */ ],
  "rowCount": 1000,
  "truncated": true,
  "truncationReason": "rows",
  "maxRows": 1000,
  "hint": "Results were truncated at 1000 rows. Add a LIMIT clause or a more selective filter and retry for a complete result."
}

호출자(LLM 에이전트 포함)는 truncated / truncationReason / hint를 프로그래밍 방식으로 읽고, 불투명한 전송 수준 실패를 보는 대신 더 좁힌 쿼리로 재시도할 수 있습니다.

제한 시간 및 취소 오류

NEO4J_CYPHER_TIMEOUT이 발동하면 도구는 구성된 제한을 명시하고 도구별 해결 방법을 제시하는 분류된 오류를 반환합니다(read-cypher의 경우 가변 길이 패턴 바인딩, WHERE 필터 추가 또는 LIMIT 사용; write-cypher의 경우 배치 크기 줄이기, MATCH 범위 좁히기 또는 apoc.periodic.iterate 사용). 호출자 취소(제한 시간과 구별됨)는 해결 방법 안내 없이 간결한 cancelled 메시지로 표시됩니다.

플래너 추정치 거부

플래너 추정치 가드는 쿼리가 실행되기 전에 EXPLAIN 계획의 루트 EstimatedRows를 읽습니다. Neo4j는 LIMIT을 루트 추정치에 반영하므로, 정당한 MATCH ... LIMIT 100 쿼리는 ~100의 추정치로 문제없이 통과하는 반면, 수백만 행 레이블에 대한 단순 MATCH는 시작 전에 거부됩니다.

인증 방법 (HTTP 모드)

HTTP 전송 모드를 사용할 때 Neo4j MCP Canary 서버는 다양한 배포 시나리오를 지원하기 위해 두 가지 인증 방법을 제공합니다.

Bearer 토큰 인증

Bearer 토큰 인증은 ID 관리를 위해 SSO/OAuth/OIDC를 사용하는 Neo4j Enterprise Edition 및 Neo4j Aura 환경과의 원활한 통합을 지원합니다. 이 방법은 다음과 같은 경우에 적합합니다:

• 중앙 집중식 ID 공급자(Okta, Azure AD 등)를 사용하는 엔터프라이즈 배포

• SSO로 구성된 Neo4j Aura 데이터베이스

• OAuth 2.0 준수가 필요한 조직

• 다중 요소 인증 시나리오

예시:

curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Bearer 토큰은 ID 공급자로부터 얻어 인증을 위해 Neo4j에 전달됩니다. MCP 서버는 통과(pass-through) 역할을 하여 토큰을 Neo4j의 인증 시스템으로 전달합니다.

기본 인증

전통적인 사용자 이름/비밀번호 인증으로, 다음과 같은 경우에 적합합니다:

• Neo4j Community Edition

• 개발 및 테스트 환경

• SSO 없는 직접 데이터베이스 자격 증명

예시:

curl -X POST http://localhost:8080/mcp \
  -u neo4j:password \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

클라이언트 구성

MCP 클라이언트(VSCode, Claude Desktop 등)에서 Neo4j MCP Canary 서버를 사용하도록 구성하려면 다음을 참조하세요:

📘 클라이언트 설정 가이드 – STDIO 및 HTTP 모드에 대한 전체 구성.

도구 및 사용법

제공되는 도구:

읽기 전용 모드 플래그

NEO4J_READ_ONLY=true로 설정하여 읽기 전용 모드를 활성화합니다(허용 값: true / false; 기본값: false).

CLI 플래그를 사용할 수도 있습니다:

neo4j-mcp-canary \
  --neo4j-uri "bolt://localhost:7687" \
  --neo4j-username "neo4j" \
  --neo4j-password "password" \
  --neo4j-read-only true

활성화하면 쓰기 도구(예: write-cypher)가 클라이언트에 노출되지 않습니다.

쿼리 분류

read-cypher는 실행 전에 호출자의 쿼리를 읽기 또는 쓰기로 분류하기 위해 쿼리 앞에 EXPLAIN을 붙입니다. 결과:

• 쓰기 작업 (CREATE, MERGE, DELETE, SET, REMOVE, ...) — 호출자를 write-cypher로 안내하는 메시지와 함께 거부됩니다.

• 스키마/DDL 작업 (CREATE INDEX, DROP CONSTRAINT, ...) — 동일한 메시지로 거부됩니다.

• 관리자 명령 (SHOW USERS, SHOW DATABASES, ...) — 동일한 메시지로 거부됩니다.

• EXPLAIN 접두사 — 플래너 추정 가드와 실행 타임아웃이 이미 폭주 쿼리 보호를 제공하며, 프로파일링된 계획은 write-cypher를 사용하라고 안내하는 전용 메시지와 함께 거부됩니다.

• PROFILE 접두사 — 호출자를 write-cypher로 안내하는 메시지와 함께 거부됩니다.

• 읽기 전용 SHOW 명령 (SHOW INDEXES, SHOW CONSTRAINTS, SHOW PROCEDURES, SHOW FUNCTIONS) — 허용됩니다.

래핑된 쿼리에서 구문 오류가 발생하면, 서버는 반환 전에 오류 텍스트, 열 오프셋, 캐럿 정렬에서 내부 EXPLAIN 접두사를 제거합니다. 따라서 오류는 호출자의 원래 쿼리가 직접 제출된 것처럼 읽힙니다.

read-cypher / write-cypher 응답 형식

드라이버 유형은 Cypher 규칙에 맞는 camelCase JSON 형태로 래핑됩니다:

• 노드: { "elementId": "...", "labels": [...], "properties": {...} }

• 관계: { "elementId": "...", "startElementId": "...", "endElementId": "...", "type": "...", "properties": {...} }

• 경로: { "nodes": [...], "relationships": [...] }

• 점: { "x": ..., "y": ..., "srid": ... } (3D의 경우 z 포함)

• Date / Time / DateTime / LocalTime / LocalDateTime / Duration: ISO 8601 문자열

더 이상 사용되지 않는 숫자형 id / startId / endId 식별자는 노출되지 않습니다 — elementId / startElementId / endElementId만 반환되는 식별자입니다.

피드백

give-feedback는 에이전트가 MCP 서버 자체에 대한 자유 형식 피드백(긍정적 또는 부정적)을 단일 feedback 문자열 인수로 제출할 수 있게 하며, 최대 300자로 제한됩니다(클라이언트가 전송 전에 스키마를 검증하지 않는 경우를 대비해 공개된 도구 스키마와 핸들러 모두에서 강제됨). 이는 서버의 도구, 동작 또는 문서에 대한 피드백을 위한 것이며, Cypher/데이터베이스 오류를 보고하기 위한 것이 아닙니다.

피드백은 서버의 다른 원격 측정 데이터와 함께 Mixpanel 이벤트로 전송되므로, 원격 측정이 활성화된 경우에만 기록됩니다(원격 측정(Telemetry) 참조) — 어느 쪽이든 도구 호출 자체는 항상 성공합니다.

사용 지침

카나리 테스트에서 얻은, LLM(또는 사람)이 read-cypher를 최대한 활용하는 데 도움이 되는 교훈:

1. 데이터베이스에서 집계하세요. count, sum, avg, collect, reduce, percentileCont, stDev 및 유사한 축소 함수는 단일 행으로 축소되며 행 상한의 영향을 받지 않습니다. UNWIND range(1, 50000) AS i RETURN sum(i) 같은 쿼리는 깨끗하게 실행됩니다. 동일한 범위를 행 단위로 스트리밍하면 행 상한에서 잘립니다.

2. 탐색적 쿼리에는 항상 LIMIT를 사용하세요. 행 상한은 LIMIT 없는 MATCH 반환을 자릅니다. 잘림 봉투의 hint 필드가 호출자에게 LIMIT를 추가하라고 안내합니다. 서버가 부과한 LIMIT보다 직접 선택한 LIMIT를 선호하세요.

3. 넓은 노드의 RETURN 프로젝션을 좁히세요. 레코드가 많은 속성을 가질 때(예: 19개 필드의 전체 Company 노드), 행 상한보다 먼저 바이트 상한이 적용됩니다. 전체 노드 대신 필요한 필드만 반환하세요(RETURN c.name, c.companyNumber).

4. 중첩 맵을 포함한 파라미터를 사용하세요. 파라미터 자리 표시자($name)는 params 객체에서 바인딩되며, 중첩 접근도 작동합니다($config.thresholds.pr). 누락된 필수 파라미터는 명확한 ParameterMissing 오류를 생성하고, 추가 파라미터는 조용히 무시됩니다.

5. 비교에서 유형을 명시적으로 지정하세요. t.amount > "foo" 같은 유형 간 비교는 null로 평가되어 모든 것을 조용히 필터링합니다 — 오류 없이 빈 결과 집합만 반환됩니다. 결과 형태가 예상과 다를 때 호출자 측에서 들어오는 파라미터 유형을 검증하세요.

6. SHOW INDEXES / SHOW CONSTRAINTS는 허용됩니다. 인덱스에 의존하는 쿼리를 작성하기 전이나 매치가 느린 이유를 디버깅할 때 유용합니다.

7. EXPLAIN과 PROFILE은 read-cypher에서 노출되지 않습니다. 폭주 쿼리 보호는 이미 플래너 추정 가드와 실행 타임아웃으로 처리됩니다. 런타임 통계가 포함된 프로파일링된 계획이 필요하면 write-cypher와 함께 PROFILE을 사용하세요.

8. 경로를 반환할 때 중복 페이로드를 주의하세요. RETURN p, nodes(p), relationships(p)는 직렬화된 페이로드를 3배로 만듭니다. 경로 또는 그 구성 요소 중 하나만 반환하고 둘 다 반환하지 마세요.

9. 장기 실행 쿼리는 분류된 오류를 반환합니다. NEO4J_CYPHER_TIMEOUT이 발생하면 오류는 타임아웃 값을 명시하고 드라이버의 원시 context deadline exceeded 대신 해결 방법(가변 길이 패턴 바인딩, WHERE 필터 추가, LIMIT 사용)을 제안합니다.

10. 누락된 데이터에는 OPTIONAL MATCH를 사용하세요. 일부 ID가 존재하지 않을 수 있는 ID 기반 조회에서 OPTIONAL MATCH는 행을 삭제하는 대신 누락에 대해 null을 반환합니다 — 배치 조회에 더 적합합니다.

11. 기본값은 임의가 아니라 보정된 값입니다. 1000행 / ~900 KB / 30s / 1M 플래너 추정치는 대부분의 탐색 및 프로덕션 쿼리를 충당합니다. 대량 내보내기 워크로드에는 늘리고, 트래픽이 많은 에이전트 배포를 서빙할 때는 줄이세요.

자연어 프롬프트 예시

Copilot 또는 다른 MCP 클라이언트에서 시도할 프롬프트:

• "내 Neo4j 인스턴스에는 무엇이 있나요? 모든 노드 레이블, 관계 유형, 속성 키를 나열해 주세요."

• "모든 Person 노드를 찾고 상위 관계를 50개 결과로 제한하여 보여주세요."

• "내 데이터베이스에 어떤 인덱스와 제약 조건이 있나요?"

• "트랜잭션 그래프를 요약해 주세요: 총 개수, 평균 금액, PageRank 기준 상위 5개 고객."

보안 팁

• 탐색에는 제한된 권한의 Neo4j 사용자를 사용하세요.

• 프로덕션 데이터베이스에서 실행하기 전에 LLM이 생성한 Cypher를 검토하세요.

• 그래프를 변경하면 안 되는 배포에는 NEO4J_READ_ONLY=true를 유지하세요.

• 변경할 특별한 이유가 없다면 Cypher 안전장치를 기본값으로 두세요.

로깅

서버는 여러 로그 레벨과 출력 형식을 지원하는 구조화된 로깅을 사용합니다.

구성

로그 레벨 (NEO4J_LOG_LEVEL, 기본값: info)

상세 수준을 제어합니다. 모든 MCP 로그 레벨을 지원합니다: debug, info, notice, warning, error, critical, alert, emergency.

로그 형식 (NEO4J_LOG_FORMAT, 기본값: text)

• text — 사람이 읽기 쉬운 형식 (기본값)

• json — 구조화된 JSON (로그 집계에 유용)

원격 측정(Telemetry)

기본적으로 neo4j-mcp-canary는 제품 개선을 위해 익명 사용 데이터를 수집합니다. 여기에는 사용 중인 도구, 운영 체제, CPU 아키텍처와 같은 정보가 포함됩니다. 개인 정보나 민감한 정보는 수집되지 않습니다.

원격 측정을 비활성화하려면 NEO4J_TELEMETRY=false로 설정하세요(허용 값: true / false; 기본값: true). --neo4j-telemetry CLI 플래그를 사용할 수도 있습니다.

문서

📘 클라이언트 설정 가이드 – VSCode, Claude Desktop 및 기타 MCP 클라이언트 구성 (STDIO 및 HTTP 모드) 📚 기여 가이드 – 기여 워크플로우, 개발 환경, 목(mocks) 및 테스트

문제 / 피드백: 재현 세부 정보를 포함하여 GitHub 이슈를 열어 주세요(민감한 데이터는 제외).