Neo4j MCP Canary — Канарейка идёт первой, чтобы остальные знали, что нас ждёт

Neo4j MCP Canary — это быстро развивающийся экспериментальный релиз сервера Neo4j MCP для клиентов, которые хотят изучать новые возможности до того, как они будут рассмотрены для официального сервера.

Созданный на основе исходного кода официального сервера Model Context Protocol (MCP) для Neo4j, этот вариант предназначен для экспериментального изучения потенциально новых возможностей.

Поскольку это лабораторный проект, имейте в виду, что:

• Он не поддерживается.

• Он может содержать критические изменения как между собственными релизами, так и по сравнению с официальным сервером Neo4j MCP.

• Перед использованием его следует протестировать.

Мы приветствуем ваш вклад — мы всегда открыты для новых идей, особенно в этом canary-канале.

Не предполагайте, что canary будет работать в вашей ситуации. Сначала протестируйте.

Предварительные требования

• Запущенный экземпляр базы данных Neo4j; варианты включают Aura, Neo4j Desktop или самостоятельно управляемый.

• Плагин APOC, установленный в экземпляре Neo4j (обязательно — get-schema использует apoc.meta.schema).

• Любой MCP-совместимый клиент (например, VSCode с поддержкой MCP).

⚠️ Известная проблема: в Neo4j 5.26.18 есть ошибка в APOC, из-за которой инструмент get-schema не работает. Это исправлено в 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) не обнаружена, сервер всё равно запускается, но автоматически отключает инструменты, зависящие от GDS, такие как list-gds-procedures. Все остальные инструменты остаются доступными.

Установка (бинарный файл)

Релизы: https://github.com/neo4j-labs/neo4j-mcp-canary/releases

1. Скачайте архив для вашей ОС/архитектуры.

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 (по умолчанию): стандартное MCP-взаимодействие через stdin/stdout для настольных клиентов (Claude Desktop, VSCode).

• HTTP: RESTful HTTP-сервер с Bearer-токеном или базовой аутентификацией для каждого запроса, предназначенный для веб-клиентов и мультитенантных сценариев. Если стандартный заголовок 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 по умолчанию

• Порт по умолчанию: автоматически используется 443, когда TLS включён

Пример

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

Использование в производстве: для производственных развёртываний используйте сертификаты от доверенного ЦС (Let's Encrypt, ЦС вашей организации и т. д.).

Подробные инструкции по генерации сертификатов, тестированию TLS и производственному развёртыванию см. в CONTRIBUTING.md.

Параметры конфигурации

Сервер neo4j-mcp-canary настраивается через переменные окружения, флаги CLI и/или необязательный файл конфигурации. Флаги CLI имеют приоритет над переменными окружения, которые, в свою очередь, имеют приоритет над необязательным файлом конфигурации.

Переменные окружения

Основные параметры подключения и поведения:

Подключение через Query API вместо Bolt

Схема NEO4J_URI определяет, какой сетевой протокол сервер использует для взаимодействия с Neo4j — отдельный флаг не нужен:

• bolt://, bolt+s://, neo4j://, neo4j+s:// и т. д. → драйвер Bolt (по умолчанию, поведение не изменилось).

• http:// или https:// → Neo4j Query API, HTTP-интерфейс запросов Neo4j. Полезно для развёртываний, которые предоставляют только HTTP или по иным причинам предпочитают не использовать Bolt.

Режим Query API требует Neo4j 2026.07 или новее (релизы с календарной версией) или 5.27-aura или новее (только классические версии Aura — чистая классическая версия без суффикса -aura не поддерживается). Этот минимальный порог на один релиз выше, чем собственная общедоступность Query API (2026.06): отклонение запросов на запись в read-cypher зависит от поля queryType в ответе на запрос, которое Neo4j представила только в 2026.07 — сервер 2026.06 не имеет надёжного сигнала, чтобы классифицировать запрос как предназначенный только для чтения до его выполнения. При запуске сервер проверяет сообщённую версию подключённого экземпляра на соответствие этому порогу (через неаутентифицированный GET к базовому URI) и отказывается запускаться, если она слишком старая, с ошибкой, в которой указаны обнаруженная версия и минимально требуемая.

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 + ключ файла конфигурации, всё сразу) означает добавление одной записи в срез fields в internal/config/schema.go — см. комментарии в документации этого файла для описания структуры.

Формат ответа (JSON и TOON)

Ответы инструментов (read-cypher, write-cypher, get-schema, list-gds-procedures) по умолчанию выводятся в формате JSON. Установите NEO4J_OUTPUT_FORMAT (или --neo4j-output-format) в значение toon, чтобы вместо этого выводить их в формате TOON (Token-Oriented Object Notation) — компактном, но по-прежнему читаемом формате, который снижает расход токенов LLM по сравнению с JSON, особенно для табличных строк, которые возвращают эти инструменты:

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

Недопустимое значение приводит к возврату к json с предупреждением в stderr, так же как и NEO4J_LOG_FORMAT.

Защитные механизмы выполнения 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, инструмент возвращает классифицированную ошибку, в которой указан настроенный лимит, и предлагает специфичные для инструмента способы исправления (ограничьте шаблоны переменной длины, добавьте фильтры WHERE или LIMIT для read-cypher; уменьшите размер пакета, сузьте MATCH или используйте apoc.periodic.iterate для write-cypher). Отмена вызывающей стороной (в отличие от тайм-аута) проявляется как краткое сообщение cancelled без рекомендаций по исправлению.

Отказ по оценке планировщика

Предохранитель оценки планировщика читает корневой EstimatedRows плана EXPLAIN до выполнения запроса. Поскольку Neo4j включает LIMIT в корневую оценку, легитимный запрос MATCH ... LIMIT 100 проходит без проблем с оценкой ~100, тогда как голый MATCH по метке с миллионами строк отклоняется до начала выполнения.

Методы аутентификации (режим HTTP)

При использовании HTTP-режима транспорта сервер Neo4j MCP Canary поддерживает два метода аутентификации для различных сценариев развёртывания.

Аутентификация по Bearer-токену

Аутентификация по Bearer-токену обеспечивает бесшовную интеграцию со средами Neo4j Enterprise Edition и Neo4j Aura, которые используют SSO/OAuth/OIDC для управления идентификацией. Этот метод идеально подходит для:

• Корпоративных развёртываний с централизованными поставщиками идентификации (Okta, Azure AD и т. д.)

• Баз данных Neo4j Aura, настроенных с SSO

• Организаций, требующих соответствия 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-токен получается от вашего поставщика идентификации и передаётся в Neo4j для аутентификации. MCP-сервер действует как прокси, пересылая токен в систему аутентификации 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

Типы драйвера оборачиваются в JSON-структуры в camelCase, соответствующие соглашениям Cypher:

• Узлы: { "elementId": "...", "labels": [...], "properties": {...} }

• Связи: { "elementId": "...", "startElementId": "...", "endElementId": "...", "type": "...", "properties": {...} }

• Пути: { "nodes": [...], "relationships": [...] }

• Точки: { "x": ..., "y": ..., "srid": ... } (и z для 3D)

• Date / Time / DateTime / LocalTime / LocalDateTime / Duration: строки в формате ISO 8601

Устаревшие числовые идентификаторы id / startId / endId не возвращаются — elementId / startElementId / endElementId являются единственными возвращаемыми идентификаторами.

Обратная связь

give-feedback позволяет агенту отправлять произвольный текстовый отзыв о самом MCP-сервере — положительный или отрицательный — в виде единственного строкового аргумента feedback, ограниченного 300 символами (ограничение применяется как в объявляемой схеме инструмента, так и в обработчике, на случай если клиент не проверяет схему перед отправкой).