neo4j-mcp-canary

Neo4j MCP Canary — カナリアが先に飛び、これから起きることを私たちに知らせます

Neo4j MCP Canary は、公式サーバーとして採用される前に新たな機能を試してみたいお客様向けの、開発の速い実験的な Neo4j MCP サーバーです。

Neo4j 用の公式 Model Context Protocol（MCP）サーバーのソースを基にしたこのバリアントは、新たな機能の可能性を実験しながら探るためのものです。

ラボプロジェクトであるため、以下にご注意ください。

• サポート対象外です
• このプロジェクト独自のリリース間、および公式 Neo4j MCP サーバーとの間で、互換性を損なう変更が含まれる場合があります
• 使用前にテストしてください

Canary がご利用の状況で動作するとは限りません。まずテストしてください。

前提条件

• 稼働中の Neo4j データベースインスタンス。選択肢には Aura、Neo4j Desktop、セルフマネージドがあります。
• Neo4j インスタンスに APOC プラグインがインストールされていること（必須 — get-schema は apoc.meta.schema を使用します）。
• MCP 対応クライアント（例：MCP サポートを備えた VSCode）。

⚠️ 既知の問題：Neo4j 5.26.18 には APOC のバグがあり、get-schema ツールが失敗します。この問題は 5.26.19 以降で修正されています。5.26.18 をお使いの場合は、アップグレードしてください。詳細は #136 をご覧ください。

起動時チェックと適応的な動作

サーバーは、環境が正しく設定されていることを確認するため、複数のチェックを実行します。

STDIO モード — 必須要件 STDIO モードでは、サーバーは以下を確認します。いずれかのチェックに失敗した場合（設定が無効、認証情報が正しくない、APOC がないなど）、サーバーは起動しません。

• Neo4j インスタンスへの有効な接続。
• クエリを実行できること。
• APOC プラグインが存在すること。
• データベースとの通信に Query API を使用するための最小バージョンチェック。

HTTP モード — 検証を省略 HTTP モードでは、認証情報がリクエストごとの認証ヘッダーから取得されるため、起動時の検証チェックは省略されます。サーバーは Neo4j に接続せず、すぐに起動します。ただし、Bolt の代わりに Query API を使用して接続する場合は例外です。リクエストごとの認証情報に依存せず、認証なしの GET のみで実行できるため、その最小バージョンチェックは両方のトランスポートモードで起動時に実行されます。

任意の要件 任意の依存関係が見つからない場合、サーバーは適応モードで起動します。たとえば、Graph Data Science（GDS）ライブラリが検出されなくてもサーバーは起動しますが、list-gds-procedures など、GDS に依存するツールは自動的に無効になります。同様に、接続先のサーバーが Cypher 25 をサポートしていない場合、graph、traversal、patterns ツールは無効になります。それ以外のツールはすべて引き続き利用できます。

インストール（バイナリ）

リリース：Canary MCP リリース

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.26 以降が必要です（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.yaml に従って GoReleaser がビルドします。ローカルでビルドする代わりにダウンロードするには、インストール（バイナリ）を参照してください。

MCP のトランスポートモード

Neo4j MCP Canary サーバーは、2 つの通信トランスポートモードに対応しています。

• STDIO（デフォルト）：デスクトップクライアント（Claude Desktop、VSCode）向けの、stdin／stdout を介した標準的な MCP 通信です。
• HTTP：Web ベースのクライアントやマルチテナントのシナリオ向けの RESTful HTTP サーバーです。リクエストごとに Bearer トークンまたは Basic 認証を使用します。標準の Authorization ヘッダーを使用できない場合は、カスタムのヘッダー名を設定できます。

主な違い

項目	STDIO	HTTP
起動時の検証	必須 — サーバーが APOC、接続性、クエリを検証します	省略 — サーバーはすぐに起動します
認証情報	環境変数で設定します	リクエストごとに Bearer トークンまたは Basic 認証ヘッダーで指定します
テレメトリ	起動時に Neo4j のバージョン、エディション、Cypher のバージョンを収集します	unknown-http-mode を報告します — リクエストごとの認証情報では内部情報を取得できません

両方のモードの設定方法については、クライアント設定ガイドを参照してください。HTTP モードは、1 台のサーバーで複数の Neo4j インスタンスを同時に接続する、別のマルチインスタンス構成にも対応しています。詳細はdocs/MULTI_INSTANCE.mdを参照してください。

認証なしの MCP クライアントリクエスト

デフォルトでは、HTTP(S) トランスポートを使用する場合、MCP クライアントが認証なしで送信できるリクエストは 4 種類あります。一部の統合（AWS AgentCore、AWS Gateway など）は、初期ヘルスチェックの仕組みとしてこの動作を利用します。

• ping
• initialize
• tools/list
• notifications/initialize

これらが不要な場合は、以下の変数で個別に認証を必須にしてください。

環境変数	CLI フラグ	デフォルト	目的
NEO4J_HTTP_ALLOW_UNAUTHENTICATED_PING	--neo4j-http-allow-unauthenticated-ping	true	認証なしの ping ヘルスチェックを許可します
NEO4J_HTTP_ALLOW_UNAUTHENTICATED_TOOLS_LIST	--neo4j-http-allow-unauthenticated-tools-list	true	認証なしのツール一覧取得を許可します
NEO4J_HTTP_ALLOW_UNAUTHENTICATED_INITIALIZE	--neo4j-http-allow-unauthenticated-initialize	true	認証なしの initialize を許可します
NEO4J_HTTP_ALLOW_UNAUTHENTICATED_NOTIFICATIONS_INITIALIZE	--neo4j-http-allow-unauthenticated-notifications-initialize	true	認証なしの notifications/initialize を許可します

TLS/HTTPS の設定

HTTP トランスポートを使用する場合は、以下の変数で TLS を有効にし、安全に通信できるようにしてください。

環境変数	CLI フラグ	デフォルト	用途
NEO4J_MCP_HTTP_TLS_ENABLED	--neo4j-http-tls-enabled	false	TLS/HTTPS を有効にします
NEO4J_MCP_HTTP_TLS_CERT_FILE	--neo4j-http-tls-cert-file	—	TLS 証明書のパス（TLS 使用時に必須）
NEO4J_MCP_HTTP_TLS_KEY_FILE	--neo4j-http-tls-key-file	—	TLS 秘密鍵のパス（TLS 使用時に必須）
NEO4J_MCP_HTTP_PORT	--neo4j-http-port	TLS 有効時は 443、無効時は 80	HTTP サーバーのポート
NEO4J_HTTP_AUTH_HEADER_NAME	--neo4j-http-auth-header-name	Authorization	認証情報を読み取るヘッダー名
NEO4J_MCP_HTTP_TOOLS_HEADER_NAME	--neo4j-mcp-http-tools-header-name	X-MCP-Tools	クライアントが 1 回のリクエストで名前によりツールを選択するためのヘッダー
NEO4J_MCP_HTTP_TOOL_CATEGORIES_HEADER_NAME	--neo4j-mcp-http-tool-categories-header-name	X-MCP-Tool-Categories	クライアントが 1 回のリクエストでカテゴリによりツールを選択するためのヘッダー

セキュリティ設定

• 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 フラグは環境変数より優先され、環境変数は任意の設定ファイルより優先されます。

環境変数

接続と動作の基本設定：

環境変数	デフォルト	用途
NEO4J_URI	—	Neo4j 接続 URI（必須）
NEO4J_USERNAME	—	データベースのユーザー名（STDIO モードでは必須、HTTP モードでは未設定にする必要があります）
NEO4J_PASSWORD	—	データベースのパスワード（STDIO モードでは必須、HTTP モードでは未設定にする必要があります）
NEO4J_DATABASE	neo4j	データベース名
NEO4J_READ_ONLY	false	true の場合、write-cypher ツールは登録されません
NEO4J_MCP_ENABLED_TOOLS	(すべて)	有効にするツール名をカンマ区切りで指定します。空の場合はすべてのツールが有効になります
NEO4J_MCP_ENABLED_TOOL_CATEGORIES	(すべて)	有効にするカテゴリ（cypher、gds、feedback、search、graph、traversal、patterns）をカンマ区切りで指定します
NEO4J_TELEMETRY	true	匿名テレメトリーを有効または無効にします
NEO4J_SCHEMA_SAMPLE_SIZE	1000	スキーマ推論時に APOC がラベルごとに調査するノード数
NEO4J_LOG_LEVEL	info	debug、info、notice、warning、error、critical、alert、emergency
NEO4J_LOG_FORMAT	text	text または json
NEO4J_OUTPUT_FORMAT	json	LLM クライアントに送信するツール応答の形式：json、toon、markdown
NEO4J_TRANSPORT_MODE	stdio	stdio または http（非推奨の NEO4J_MCP_TRANSPORT に代わる設定です）
NEO4J_MCP_EMBEDDING_PROVIDER	—	set-vector-property の text フィールド／check-embedding-dimensions 用の GenAI 埋め込みプロバイダー：openai、azure-openai、vertexai、bedrock-titan。未設定の場合、両方とも無効になります
NEO4J_MCP_EMBEDDING_CONFIGURATION	—	上記プロバイダーの key=value 設定をカンマ区切りで指定します（例：token=sk-xxx,model=text-embedding-3-small）。プロバイダーごとに必要なキーについては、マルチインスタンス HTTP モードを参照してください。neo4j_instances とは併用できません（代わりに、そこでインスタンスごとに埋め込みを設定してください）

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.26-aura 以降（従来のバージョン形式の Aura リリースのみ）が必要です。-aura サフィックスのない従来のバージョンはサポートされていません。セルフマネージドの従来型サーバーは、このサーバーの Query API クライアントが依存する型付き JSON メディアタイプのバージョンより前のものだからです。この下限は、Query API 自体の一般提供開始（2026.06）より1リリース後です。read-cypher で書き込みクエリを拒否するには、クエリ応答内の queryType フィールドが必要ですが、Neo4j がこれを導入したのは 2026.07 です。2026.06 のサーバーには、クエリを実行する前に読み取り専用かどうかを判別する信頼できる手段がありません。サーバーは起動時に（ベース URI に認証なしで GET リクエストを送信して）接続先インスタンスが報告するバージョンをこの下限と照合し、古すぎる場合は、検出したバージョンと必要な最小バージョンを示すエラーを出して起動を拒否します。

NEO4J_USERNAME／NEO4J_PASSWORD およびリクエストごとの Basic／Bearer 認証情報は、Query API モードでも Bolt と同様に機能します。トランスポートモード と認証方式（HTTP モード）を参照してください。

Cypher 実行の保護機能については、Cypher 実行の保護機能を参照してください。

環境変数	デフォルト	目的
NEO4J_CYPHER_MAX_ROWS	1000	read-cypher／write-cypher の呼び出しごとの行数上限。0 で無効化します
NEO4J_CYPHER_MAX_BYTES	900000	テキストと構造化出力を合わせた、呼び出しごとのバイト数上限（約 900 KB）。0 で無効化します
NEO4J_CYPHER_TIMEOUT	30	実行タイムアウト（秒）。0 で無効化します
NEO4J_CYPHER_MAX_ESTIMATED_ROWS	1000000	EXPLAIN 時のプランナー推定値がこの値を超える場合、read-cypher はクエリを拒否します。0 で無効化します

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-mcp-enabled-tools — NEO4J_MCP_ENABLED_TOOLS を上書きします（ツール名をカンマ区切りで指定）
• --neo4j-mcp-enabled-tool-categories — NEO4J_MCP_ENABLED_TOOL_CATEGORIES を上書きします（カテゴリーをカンマ区切りで指定）
• --neo4j-telemetry — NEO4J_TELEMETRY を上書きします（true / false）
• --neo4j-schema-sample-size — NEO4J_SCHEMA_SAMPLE_SIZE を上書きします
• --neo4j-output-format — NEO4J_OUTPUT_FORMAT を上書きします（json / toon / markdown）
• --neo4j-mcp-embedding-provider — NEO4J_MCP_EMBEDDING_PROVIDER を上書きします
• --neo4j-mcp-embedding-configuration — NEO4J_MCP_EMBEDDING_CONFIGURATION を上書きします（key=value ペアをカンマ区切りで指定）

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-mcp-http-tools-header-name — NEO4J_MCP_HTTP_TOOLS_HEADER_NAME を上書きします
• --neo4j-mcp-http-tool-categories-header-name — NEO4J_MCP_HTTP_TOOL_CATEGORIES_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）も使用できます。2 つのキーを除き、すべてのキーでスカラー値（文字列、数値、ブール値）のみがサポートされます。それ以外のキーにネストされたオブジェクトやリストがある場合、起動エラーになります。CLI フラグまたは環境変数の値は常に設定ファイルより優先されます。読み込みまたは解析に失敗する --config-file は起動エラーになります。

唯一の例外は neo4j_instances です。これは Neo4j インスタンス定義のリストで、マルチインスタンス HTTP モードを有効にし、1 つのサーバーから複数の Neo4j インスタンスに同時に接続できるようにします。各インスタンスには、それぞれ固有の URL パスからアクセスできます。この設定は設定ファイルでのみ指定できます。設定全体の形式、インスタンスごとの認証タイプ、クライアントによるインスタンスの選択方法については、docs/MULTI_INSTANCE.md を参照してください。

ファイルでのみ指定できるもう 1 つのキー custom_tools を使うと、独自の Cypher ベースのツールを定義できます。詳しくは docs/CUSTOM_TOOLS.md を参照してください。

neo4j-mcp-canary --validate-config を（通常使用しているフラグ、環境変数、--config-file とともに）実行すると、サーバーを起動せずに設定全体を検証できます。最初の問題だけでなく、見つかったすべての問題が報告されます。エラーがある場合は、ステータス 1 で終了します。検証内容については、docs/CUSTOM_TOOLS.md を参照してください。

サーバーに新しい設定パラメーター（環境変数、CLI フラグ、設定ファイルのキーを一度にすべて）を追加するには、internal/config/schema.go の fields スライスにエントリーを 1 つ追加します。形式については、そのファイルのドキュメントコメントを参照してください。

レスポンス形式（JSON、TOON、または Markdown）

ツールのレスポンス（上の表にあるすべてのツール）は、デフォルトでは JSON として出力されます。NEO4J_OUTPUT_FORMAT（または --neo4j-output-format）を toon または markdown に設定すると、別の形式で出力できます。

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

JSON 形式の read-cypher の結果：

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

同じ結果を TOON（Token-Oriented Object Notation）で表したものです。コンパクトでありながら人が読みやすい形式で、特にこのツールが返す表形式の行データでは、JSON より LLM のトークン使用量を削減できます。

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

同じ結果を markdown で表したものです。形式が統一されたフラットな行の配列はテーブルとして、ネストされたデータや形式が統一されていないデータ（例：get-schema の出力）はネストされた箇条書きとして出力されます。

- **rowCount**: 2
- **rows**:
| age | name |
| --- | --- |
| 30 | Alice |
| 25 | Bob |
- **truncated**: false

markdown は toon を厳密に上回る形式ではなく、補完する形式です。表形式のデータを対象とした独立したベンチマークでは、Markdown テーブルの方がトークンを多く使う一方で、TOON より高い 精度 を示しました。一方、生のトークン数では TOON が優れています。トークン予算を最優先する場合は toon を、結果の精度を最優先する場合は markdown を選んでください。

無効な値が指定された場合は、NEO4J_LOG_FORMAT と同様に、stderr に警告を出して json にフォールバックします。

構造化出力（structuredContent / outputSchema）

すべてのツール呼び出し結果には、MCP の構造化出力拡張も含まれます。上記のテキストブロック（NEO4J_OUTPUT_FORMAT で選択された形式）のほか、結果の structuredContent フィールドには常に同じデータが標準の JSON として格納され、ツール定義で公開される outputSchema と一致します。結果をプログラムから扱うクライアントは、設定されているテキスト形式にかかわらず、テキストブロックを再解析する代わりに structuredContent を直接読み取ることができます。

structuredContent はテキストブロック内のペイロードを複製するため、read-cypher／write-cypher では NEO4J_CYPHER_MAX_BYTES を合算の上限として適用します。ストリーミング時に実際に適用されるバイト数の上限は設定値の半分です。そのため、テキストと構造化データを合わせても、以下で説明する約 900 KB／1 MB の想定範囲内に収まり、2 倍にはなりません。

Cypher 実行の保護策

read-cypher と write-cypher には、過剰に実行しようとする LLM によって MCP トランスポートがハングしたり、データベースのリソースが枯渇したりするのを防ぐため、4 層の保護策が設けられています。各層は異なる障害モードを検出し、連携して多層防御として機能します。

層	設定	デフォルト	発動するタイミング
プランナーの推定値	NEO4J_CYPHER_MAX_ESTIMATED_ROWS	1000000	実行前 — プランナーのルート EstimatedRows がしきい値を超えるとクエリを拒否します
実行タイムアウト	NEO4J_CYPHER_TIMEOUT	30s	実行中 — 期限を過ぎるとクエリをキャンセルします
行数上限	NEO4J_CYPHER_MAX_ROWS	1000	ストリーミング中 — 行数の上限に達するとレスポンスを切り詰めます
バイト数上限	NEO4J_CYPHER_MAX_BYTES	900000	ストリーミング中 — エンベロープが設定値の半分を超えるとレスポンスを切り詰めます（構造化出力を参照）

値を 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 サーバーは、さまざまなデプロイシナリオに対応するため、2 種類の認証方法をサポートしています。（このセクションでは単一インスタンスの HTTP モードを扱います。マルチインスタンスモードには、サーバーで検証される Bearer トークンなど、インスタンスごとの独自の認証タイプがあります。詳しくは docs/MULTI_INSTANCE.md を参照してください。）

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 サーバーはパススルーとして機能し、トークンを Neo4j の認証システムに転送します。

Basic 認証

従来型のユーザー名／パスワード認証で、次の用途に適しています。

• 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 モードの完全な設定手順です。

ツールと使用方法

提供されるツール：

ツール	カテゴリ	読み取り専用	目的	備考
get-schema	cypher	true	ラベル、リレーションシップタイプ、プロパティキーを調査します	apoc.meta.schemaを使用します。サンプリングはNEO4J_SCHEMA_SAMPLE_SIZEで制御します。
read-cypher	cypher	true	任意の読み取り専用Cypherを実行します	書き込み、スキーマ／管理用DDL、EXPLAIN、PROFILEを拒否します。Cypher実行の安全対策を参照してください。
write-cypher	cypher	false	任意のCypherを実行します（書き込みモード）	注意： LLMが生成したクエリは損害を引き起こす可能性があります。開発環境でのみ使用してください。EXPLAIN／PROFILEで始まるクエリは拒否されます（下記参照）。NEO4J_READ_ONLY=trueの場合は登録されません。
explain-cypher	cypher	true	クエリを実行せずに実行計画を返します	EXPLAINは実行されないため、読み取り文と書き込み文のどちらにも対応します。クエリの計画とプロファイリングを参照してください。
profile-cypher	cypher	false	クエリを実行し、結果と実行時統計付きのプロファイリング済み実行計画を返します	オペレーターごとのdbHits／rows／time／ページキャッシュ統計を返します。NEO4J_READ_ONLY=trueの場合は登録されません。
list-constraints-and-indexes	cypher	true	データベースの制約とインデックスを一覧表示します	構造化された情報を取得します。存在する場合はVECTOR／FULLTEXTの行も含まれます。スキーマ管理ツールを参照してください。
create-constraint	cypher	false	UNIQUENESS、KEY、またはPROPERTY_EXISTENCE制約を作成します	KEY／PROPERTY_EXISTENCEにはEnterprise Editionが必要です。構造化フィールドのみを使用するため、Cypherは不要です。
drop-constraint	cypher	false	名前を指定して制約を削除します	冪等です（DROP CONSTRAINT ... IF EXISTS）。
create-index	cypher	false	RANGE、TEXT、POINT、またはLOOKUPインデックスを作成します	VECTOR／FULLTEXTインデックスは、代わりにsearchカテゴリのcreate-vector-index／create-fulltext-indexで作成します。
drop-index	cypher	false	名前を指定してインデックスを削除します	ベクター／全文検索を含む、あらゆる種類のインデックスに対応します。
vector-search	search	true	ベクターインデックスを対象に近似最近傍類似検索を実行します	インデックスから対象のラベル／リレーションシップタイプを自動検出します。ベクター検索および全文検索ツールを参照してください。
fulltext-search	search	true	全文検索インデックスを対象にLuceneベースの全文検索を実行します	vector-searchと同様に自動検出します。
create-vector-index	search	false	類似検索用のベクターインデックスを作成します	filterablePropertiesを指定すると、後でvector-searchのfiltersで使用できるプロパティが登録されます。
create-fulltext-index	search	false	テキスト検索用の全文検索インデックスを作成します	複数のラベル／リレーションシップタイプに対応します。
set-vector-property	search	false	ノードまたはリレーションシップの埋め込みベクタープロパティを設定します	db.create.setNodeVectorProperty／setRelationshipVectorPropertyを使用します。フィルターが少なくとも1つ必要です。事前計算済みのvector、またはインスタンスに埋め込みプロバイダーが設定されている場合はサーバー側で埋め込むためのtextを指定できます。マルチインスタンスHTTPモードを参照してください。
check-embedding-dimensions	search	true	設定済みの埋め込みプロバイダー／モデルがベクターインデックスの次元数に適合するか検証します	使い捨ての埋め込みを1つ生成しますが、何も書き込みません。インスタンスに埋め込みプロバイダーが設定されている必要があります。
create-node	graph	false	ラベルとプロパティを指定してノードを作成します	mergeOnを指定すると、冪等なアップサートになります。ノードのidを返します。グラフ操作ツールを参照してください。
find-nodes	graph	true	ラベル、プロパティ値、またはフィルターでノードを検索します	ページネーションに対応しています（limit／skip）。returnPropertiesで出力を絞り込めます。
get-node	graph	true	1つのノードと、タイプおよび方向別のリレーションシップ数を取得します	idまたは一意キーで指定します。
update-node	graph	false	既存のノードのプロパティを設定／削除し、ラベルを追加／削除します	maxAffected（デフォルトは1）とdryRunで制限されます。id、match、またはfiltersが必要です。
delete-node	graph	false	ノードを削除します	破壊的な操作です。 関連ノードを削除するにはdetachが必要です。maxAffectedとdryRunで制限されます。
count-nodes	graph	true	ラベル／プロパティ／フィルターに一致するノード数を数えます	数だけが必要な場合は、find-nodesより効率的です。
create-relationship	graph	false	既存の2つのノード間に有向リレーションシップを作成します	始点と終点は、それぞれノードを1つだけ選択する必要があります。allowDuplicateを指定しない限り、同一のリレーションシップは再利用されます。
find-relationships	graph	true	タイプ、端点ノード、またはプロパティでリレーションシップを検索します	端点ノードの概要を返すため、追加の検索は不要です。
update-relationship	graph	false	既存のリレーションシップのプロパティを設定／削除します	maxAffectedとdryRunで制限されます。
delete-relationship	graph	false	リレーションシップを削除します（端点ノードは保持されます）	破壊的な操作です。 maxAffectedとdryRunで制限されます。
traverse	traversal	true	ノードから外向きにたどり、深さ付きの到達可能ノードまたはパスを取得します	maxDepth（最大10）で制限されます。依存関係、階層、影響分析に使用できます。
expand-neighbors	traversal	true	ノードからちょうど1ホップ以内にあるすべてのノードを取得します	方向は開始ノードを基準にして示されます。
find-shortest-path	traversal	true	2つのノード間の最短経路（または同じ長さの最短経路すべて）を取得します	Cypher 25のANY／ALL SHORTESTを使用します。
find-all-paths	traversal	true	2つのノード間の経路を、最短のものから列挙します	maxDepth（最大8）とlimitで制限されます。
match-pattern	patterns	true	説明されたパターンの出現箇所を検索し、行、件数、または存在有無を返します	パターンはCypherではなく、ノードとリレーションシップで指定します。連結されている必要があります。
find-common-connections	patterns	true	指定した2〜5個のノード間で共有されるノード（共通の隣接ノード）を検索します	コラボレーション、共有依存関係、共通のつながりに使用できます。
find-motif	patterns	true	star、fan-in、fan-out、triangle、またはcycleの形状を検出します	高速化するにはrelationshipTypes／nodeLabelsを指定します。startで開始点を指定します。
find-relationship-chain	patterns	true	ノードから、順序を厳密に指定したリレーションシップ列をたどります	各ステップでタイプ、方向、任意の対象ノード条件を指定します。
find-subgraph	patterns	true	ノードの周辺をノードとリレーションシップとして抽出します	maxDepth（最大4）とmaxNodes（最大200）で制限されます。
list-gds-procedures	gds	true	Neo4jインスタンスで利用可能なGDSプロシージャを一覧表示します	GDSがインストールされていない場合は自動的に無効になります。
give-feedback	feedback	true	MCP サーバー自体について自由記述のフィードバックを送信します	サーバー（ツール、動作、ドキュメント）へのフィードバック用です。Cypher／データベースの問題は対象外です。300文字までです。フィードバックを参照してください。

公開するツールの選択

各ツールは、必ず1つのカテゴリ（上の表に記載された cypher、gds、feedback、search、graph、traversal、patterns のいずれか）に属し、ラベル（MCP タイトル注釈。例：「Read Cypher」）を持っています。これは、親しみやすいツール名を表示するクライアントに表示されます。

ツールの選択は、既存の NEO4J_READ_ONLY／GDS の利用可否／検索バージョン／Cypher 25 のフィルタリングと組み合わせて、2つの方法でさらに絞り込めます（選択によって対象をさらに絞ることはできますが、これらのフィルターですでに除外されたツールを再び有効にすることはできません）。

起動時に静的に、NEO4J_MCP_ENABLED_TOOLS および／または NEO4J_MCP_ENABLED_TOOL_CATEGORIES を使用します（カンマ区切りです。いずれかのリストに一致するツールが有効になります。設定オプションを参照してください）。

# Only expose the two Cypher read tools:
export NEO4J_MCP_ENABLED_TOOLS="read-cypher,get-schema"

# Only expose the cypher category (equivalent to the above plus write-cypher):
export NEO4J_MCP_ENABLED_TOOL_CATEGORIES="cypher"

HTTP モードでリクエストごとに、X-MCP-Tools および X-MCP-Tool-Categories ヘッダーを使用します（ヘッダー名は NEO4J_MCP_HTTP_TOOLS_HEADER_NAME／NEO4J_MCP_HTTP_TOOL_CATEGORIES_HEADER_NAME で設定できます）。どちらのヘッダーも指定しないリクエストでは、通常どおり静的に有効化されたすべてのツールが表示されます。いずれかのヘッダーを設定したリクエストでは、そのリクエストに限り、一致するツールのみが表示されます。除外されたツールを呼び出すと、存在しないツールを呼び出した場合と同様に失敗します。

curl -X POST https://your-server/mcp \
  -H "Authorization: Basic <credentials>" \
  -H "X-MCP-Tool-Categories: gds" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

読み取り専用モードフラグ

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 プレフィックス— クエリプランには explain-cypher、実行時統計情報を含むプロファイル済みプランには profile-cypher を使うよう案内するメッセージとともに拒否されます。
• PROFILE プレフィックス— クエリを実行し、結果とプロファイル済みプランの両方を返す profile-cypher を使うよう案内するメッセージとともに拒否されます。同じ理由で、write-cypher も EXPLAIN／PROFILE プレフィックスを拒否します。クエリのプランニングとプロファイリングを参照してください。
• 読み取り専用の SHOW コマンド（SHOW INDEXES、SHOW CONSTRAINTS、SHOW PROCEDURES、SHOW FUNCTIONS）— 許可されます。

ラップされたクエリで構文エラーが発生した場合、サーバーはエラーを返す前に、エラーテキスト、列オフセット、キャレットの位置合わせから内部の EXPLAIN プレフィックスを取り除きます。これにより、呼び出し元が元のクエリを直接送信した場合と同じようにエラーが表示されます。

クエリのプランニングとプロファイリング

explain-cypher と profile-cypher は、read-cypher／write-cypher では意図的に扱わないクエリチューニングのワークフローをカバーします。explain-cypher は、読み取りか書き込みかを問わず、あらゆるステートメントについて、実行せずにプランナーのプランツリーを返します。EXPLAIN はクエリを実行しないためです。profile-cypher はステートメントを実行し、結果と、オペレーターごとの実行時統計情報（dbHits、rows、time、ページキャッシュのヒット率）を含むプロファイル済みプランの両方を返します。どちらのツールも、すでに EXPLAIN／PROFILE が付いたクエリは受け付けません。各ツールは内部で独自のプレフィックスを付け、呼び出し元が指定したプレフィックスを、実際に必要としているツールを案内するメッセージとともに拒否します。

スキーマ管理ツール

list-constraints-and-indexes、create-constraint、drop-constraint、create-index、drop-index は、構造化フィールドのみを使用して制約とインデックスを管理します。いずれも生の Cypher は受け付けず、返しません。create-constraint は UNIQUENESS、KEY、PROPERTY_EXISTENCE 制約に対応しています（KEY／PROPERTY_EXISTENCE には Enterprise Edition が必要です。Community Edition では作成時に拒否され、再試行しても解決しません）。create-index は RANGE、TEXT、POINT、LOOKUP インデックスに対応しています。ベクトルインデックスと全文検索インデックスは、代わりに search カテゴリの create-vector-index／create-fulltext-index で作成します。drop-index は、ベクトルや全文検索のインデックスも含め、あらゆる種類のインデックスに対応しています。すべての create-* ツールは、生成するステートメントに必ず IF NOT EXISTS／IF EXISTS を含めるため、同じ引数で安全に再試行できます。name を省略すると、後で対応する drop-* ツールに使用できる生成済みの名前がレスポンスで返されます。

ベクトル検索と全文検索のツール

search カテゴリの vector-search、fulltext-search、create-vector-index、create-fulltext-index、set-vector-property、check-embedding-dimensions は、構造化フィールドのみを通じて Cypher 25 の SEARCH 句を利用できます。このカテゴリのツールは、生の Cypher を受け付けず、返しません。vector-search／fulltext-search は、インデックス自体から対象のノードラベルまたはリレーションシップタイプを自動検出するため、呼び出し側が指定する必要があるのはインデックス名だけです。vector-search の filters が機能するのは、create-vector-index の filterableProperties を使ってインデックス作成時にフィルタリング可能として登録されたプロパティのみです。それ以外のプロパティでのフィルタリングはツールの制限ではなく、Neo4j の厳格な制限です。set-vector-property には、呼び出し側が指定する埋め込みベクトル（vector）か、埋め込み対象の生テキスト（text）のどちらかを渡します。後者が機能するのは、接続先の Neo4j インスタンスで埋め込みプロバイダーが設定されている場合に限ります。単一インスタンスモード（STDIO または単一インスタンスの HTTP）では NEO4J_MCP_EMBEDDING_PROVIDER／NEO4J_MCP_EMBEDDING_CONFIGURATION を介して、マルチインスタンス HTTP モードでは各エントリーの embedding ブロックを介して設定します（どちらにも適用されるプロバイダー／必須キーの一覧は、マルチインスタンス HTTP モードを参照してください）。実際に埋め込みを生成するのはプロバイダーによって異なります。openai の場合、この MCP サーバー自体が直接 HTTP 呼び出しで生成します（baseUrl 設定キーを使って LM Studio や Ollama などのローカルな OpenAI 互換サーバーに転送でき、Neo4j 側の関与は一切ありません）。一方、azure-openai／vertexai／bedrock-titan の場合は、Neo4j 独自の GenAI プラグイン（ai.text.embed）が、既に実装されている認証方式を再利用して生成します。いずれの場合も、対応するベクトルインデックスが既にある場合は、書き込み前に生成されたベクトルの次元数がインデックスと照合されます。また、check-embedding-dimensions を使えば、何も書き込まずにプロバイダー／モデルがインデックスに適合するかを事前に検証できます。

このカテゴリを使用するには、カレンダーバージョンが 2026.09.0 以上、またはクラシック Aura が 5.27-aura 以上のサーバーが必要です（ネイティブの全文検索 SEARCH 句への対応は、Neo4j の 2026.09 リリースで提供されました。ベクトル検索だけであれば 2026.01 から動作しますが、一貫性を保つため、カテゴリ全体により高い下限が適用されます）。この下限を下回る場合、6 つのツールは呼び出し時に失敗するのではなく、GDS がインストールされていない場合に list-gds-procedures が除外されるのと同じように、tools/list から自動的に除外されます。

グラフ操作ツール

graph、traversal、patterns の各カテゴリを使うと、エージェントは Cypher を一切記述せずにグラフデータを作成、読み取り、更新、削除、探索できます。入力はすべて構造化フィールドであり、これらのカテゴリのツールは生の Cypher を受け取ったり返したりしません。値は常にクエリパラメーターとしてバインドされ、ラベル、タイプ、プロパティキーはバッククォートでエスケープされます。また、フィルター演算子と列挙値は、データベースに渡される前に固定リストと照合されます。

• graph — ノードとリレーションシップの CRUD：create-node、find-nodes、get-node、update-node、delete-node、count-nodes、create-relationship、find-relationships、update-relationship、delete-relationship。
• traversal — 接続の探索：traverse（到達可能性、依存関係、階層）、expand-neighbors（1 ホップ）、find-shortest-path、find-all-paths。
• patterns — 構造に関する質問：match-pattern、find-common-connections、find-motif、find-relationship-chain、find-subgraph。

各ツールの連携方法：

• ノードとリレーションシップはすべて id（その elementId）とともに返され、ほかのすべてのツールで受け付けられるため、クエリを記述せずに結果を連鎖できます。ノードの選択方法はどこでも同じです。id、labels、完全一致の match マップ、そして／または filters（=, <>, <, >, <=, >=, IN, CONTAINS, STARTS WITH, ENDS WITH, IS NULL, IS NOT NULL を使う {property, operator, value}）で指定します。
• 結果は必要最小限です。要求したプロパティがノードまたはリレーションシップにない場合、null として返すのではなく省略されます。
• すべてに上限があります。結果にはデフォルトの limit とハード上限があり、可変長ツールには上限付きの maxDepth が設定されています。また、通常の行数上限、バイト数上限、NEO4J_CYPHER_TIMEOUT が適用されます。タイムアウトエラーには、リクエストを絞り込む方法が示されます。
• 書き込みツールは、設計上安全です。update-* と delete-* はラベルまたはタイプのみを指定した操作を拒否し、変更対象を最大 maxAffected 件（デフォルト 1、最大 1000）に制限します。選択対象がそれより多い場合は操作せず、一致件数とともに performed: false を報告します。また、影響を事前に確認するための dryRun も受け付けます。delete-node は、detach が設定されていない限り、リレーションシップが残っているノードを削除しません。すべての書き込みツールには書き込みツールであることを示す注釈が付いているため、NEO4J_READ_ONLY=true の場合は登録されません。
• ツールの説明には、同種のほかのツールではなくそのツールを使うべき状況が記載されています。エラーメッセージには、何が問題だったか、何が有効か、次に何をすべきかが示されます。

これらのツールは Cypher 25 を出力します。接続先のサーバーがこれに対応していない場合（2025.06 より前のカレンダーバージョン形式のリリース、セルフマネージドの従来型 5.x サーバー、または 5.26-aura より前の従来型 Aura）、呼び出し時にエラーになるのではなく、tools/list から 3 つのカテゴリが除外されます。これは、GDS がインストールされていない場合に list-gds-procedures が除外されるのと同じです。

ツール設計の原則

新しいツールは、以下の原則に従います。これらの原則は、このリポジトリで作業する AI コーディングエージェント向けに AGENTS.md にも記載されています。

1. 意図 — ツールは、ユーザーが名前を挙げるような特定のタスクを 1 つ解決します。名前は kebab-case の動詞-名詞形式にし、類似ツールではなくそのツールを使うべき状況を説明に記載します。
2. コンテキスト — ツールによってモデルが混乱したり、コンテキストが肥大化したりしないようにします。パラメーターの数を抑え、自由入力テキストより列挙型を優先し、ツールが返すものと実行しないことを明記します。すべてのツールが各クライアントのコンテキストを消費するため、よく似たツールを追加するのではなく、重複するツールを統合し、デプロイ時に不要なものを無効化できるようカテゴリに分類します。
3. 粒度 — 常に一緒に実行される 3〜4 個の基本操作（対象の解決、ガードの確認、書き込み、結果の返却）を 1 つの高レベルなツールにまとめます。モードをフラグで増やすのではなく、タスク単位で統合します。
4. 効率 — LLM に必要なフィールドだけを返します。連鎖処理用の ID を含め、デフォルトでは要約を返し、それ以外のフィールドは射影オプションで指定できるようにし、デフォルト値と上限が設定された limit／maxDepth を用意します。
5. 安全性 — 危険なツール（削除、上書き、その他取り消し不能な操作）は、その旨を明示しなければなりません。readOnly: false と破壊的操作を示すアノテーションを設定し、NEO4J_READ_ONLY の場合は削除します。読み取りと書き込みは別のツールにします。対象を厳密に指定するよう求め（「ラベル X のすべて」のような指定は禁止）、影響範囲に上限（maxAffected）を設け、dryRun を提供します。
6. エラー処理 — エラーには、間違っていた点、有効な値、次に試すべきこと、再試行が有効かどうかを含め、LLM が間違いを修正する方法を示す必要があります。
7. パラメーターのみ — ツールが受け取るのは構造化フィールドのみで、Cypher は受け取りません。値はパラメーターとしてバインドし、識別子はエスケープし、演算子と列挙型は許可リストで制限します。
8. 上限設定 — すべてのツールに、1 回の呼び出しが際限なく実行されないよう、行数、深さ、実行時間の上限を設定します。
9. 冪等性 — 安全に再試行できる操作（MERGE、IF NOT EXISTS、値の設定など）を優先し、再試行が安全な場合は説明に記載します。
10. 組み合わせやすさ — 出力は安定した形式にし、他のツールが入力として受け取れる ID を含めます。
11. 検証済み — ツールが生成する Cypher は、ユニットテストを備えた純粋関数で組み立てます。データベースにアクセスするすべてのツールには、インテグレーションテストを用意します。

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 id／startId／endId は返されません。返される識別子は elementId／startElementId／endElementId のみです。

フィードバック

give-feedback を使うと、エージェントは MCP サーバー自体に関する肯定的または否定的な自由記述のフィードバックを、単一の feedback 文字列引数で送信できます。文字数は最大 300 文字に制限されており、この制限は公開されるツールスキーマとハンドラーの両方で適用されます。これはクライアントが送信前にスキーマを検証しない場合に備えたものです。このツールはサーバーのツール、動作、ドキュメントに対するフィードバック用であり、Cypher／データベースのエラーを報告するためのものではありません。

フィードバックは Mixpanel イベントとしてサーバーの他のテレメトリーとともに送信されるため、テレメトリーが有効な場合にのみ記録されます（テレメトリーを参照）。どちらの場合も、ツールの呼び出し自体は常に成功します。

使用ガイダンス

カナリアテストから得られた、LLM（または人）が read-cypher を最大限に活用するためのヒントです。

1. データベース内で集計します。 count、sum、avg、collect、reduce、percentileCont、stDev などの集計処理は、結果を1行にまとめるため、行数上限の影響を受けません。UNWIND range(1, 50000) AS i RETURN sum(i) のようなクエリは問題なく実行されますが、同じ範囲を1行ずつストリーミングすると、行数上限で切り捨てられます。
2. 探索クエリでは必ず 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 では公開されていません。 プランナーの推定値によるガードと実行タイムアウトによって、処理が暴走するクエリへの対策はすでに講じられています。クエリプランには explain-cypher を、実行時統計を含むプロファイル済みプランには profile-cypher を使ってください。
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（ログの集約に便利）

テレメトリー

デフォルトでは、neo4j-mcp-canary は製品の改善に役立てるため、匿名の使用状況データを収集します。これには、使用されているツール、オペレーティングシステム、CPU アーキテクチャなどの情報が含まれます。個人情報や機密情報は収集されません。

テレメトリーを無効にするには、NEO4J_TELEMETRY=false を設定してください（指定可能な値：true / false、デフォルト：true）。--neo4j-telemetry CLI フラグも使用できます。

ドキュメント

📘 クライアント設定ガイド – VSCode、Claude Desktop、その他の MCP クライアントを設定します（STDIO モードと HTTP モード） 📚 コントリビューションガイド – コントリビューションのワークフロー、開発環境、モックとテスト

問題やフィードバック：再現手順の詳細を添えて GitHub issue を作成してください（機密情報は含めないでください）。