Elasticsearch MCPサーバーの使い方 — 非推奨化とAgent Builder移行

Elasticsearch向けの公式MCPサーバーelastic/mcp-server-elasticsearchは、READMEの冒頭に非推奨(deprecated)の警告が入っています。今後は重大なセキュリティ更新のみが提供され、後継として案内されているのはElastic Agent Builderが提供するMCPエンドポイントです。すでに動いている接続を持つチームは既存の手順を知っておく必要があり、これから新規に繋ぐチームは、後継として案内されているAgent Builder側が選択肢になります。両方の接続方法と、何が変わったのかをまとめます。

Elasticsearch MCPサーバーで何ができるか

MCPはAIエージェントと外部ツールをつなぐ標準プロトコルです。仕組み自体はMCPとはにまとめています。ElasticsearchのMCPサーバーが提供する役割は明快で、インデックスに対する自然言語での検索・分析です。SQLでもDSLでもなく、日本語や英語の質問文のままElasticsearchのデータに触れます。

現行サーバーが公開しているツールは5つです。

スキーマをget_mappingsで把握してからsearchやesqlで問い合わせる、という流れがそのままAIエージェントの思考過程に載る形です。運用状態を見たいときはget_shardsでシャードの分布を確認できます。

現行サーバーの接続手順(Docker)

現行のmcp-server-elasticsearchはDockerコンテナイメージとして配布されており、docker.elastic.co/mcp/elasticsearchから取得します。プロトコルはstdioとstreamable-HTTPの2つから選べます(SSEは非推奨)。

接続前に、ElasticsearchクラスターのURLと認証情報を用意します。認証はAPIキーかユーザー名・パスワードのどちらかです。

docker run -i --rm \
  -e ES_URL \
  -e ES_API_KEY \
  docker.elastic.co/mcp/elasticsearch \
  stdio

Claude Desktopに登録する設定はJSON形式で、環境変数をenvブロックに直接書き込みます。

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "ES_URL",
        "-e", "ES_API_KEY",
        "docker.elastic.co/mcp/elasticsearch",
        "stdio"
      ],
      "env": {
        "ES_URL": "<elasticsearch-cluster-url>",
        "ES_API_KEY": "<elasticsearch-API-key>"
      }
    }
  }
}

Webベースの統合や複数クライアントからの同時接続には、streamable-HTTPモードのほうが向いています。

docker run --rm \
  -e ES_URL \
  -e ES_API_KEY \
  -p 8080:8080 \
  docker.elastic.co/mcp/elasticsearch \
  http

このモードではエンドポイントがhttp://<host>:8080/mcp、ヘルスチェックがhttp://<host>:8080/pingで応答します。stdioしか対応していないクライアント(Claude Desktopの無償版など)からHTTPサーバーに繋ぎたい場合は、mcp-proxyでstdioとstreamable-HTTPの橋渡しをします。

コンテナが動いているかはdocker psで、/pingの応答はcurlで確かめます。

docker ps | grep elasticsearch-mcp-server
curl http://localhost:8080/ping

/pingがpongを返せば、サーバー自体は動いています。Elasticsearchまで届いているかは別の問題で、切り分けにはコンテナの中からcurlを打ちます。

docker exec <container-id> curl -k -H "Authorization: ApiKey <api-key>" <ES_URL>

クラスターの情報が返れば、コンテナからクラスターまでの経路と認証は通っています。-kは証明書の検証を飛ばす指定なので、検証用の環境に限って使います。接続不良の原因調査にはdocker logs <container-id>も使えます。

後継のAgent Builder MCPエンドポイントへの移行

Elastic Agent Builderは、Kibana側で管理するツール群を外部のMCPホストに公開する仕組みです。エンドポイントは次の形式で、Kibana Spaceを使っている場合はスペース名をパスに含めます。

{KIBANA_URL}/api/agent_builder/mcp
{KIBANA_URL}/s/{SPACE_NAME}/api/agent_builder/mcp

利用できる範囲はデプロイ形態で分かれます。Serverless版のElasticsearch・Observability・Securityプロジェクトはいずれも一般提供(GA)済みです。Elastic Stackでは9.3でGA、9.2ではプレビュー扱いです。旧サーバーのDocker配布と違い、こちらはKibanaの機能として組み込まれているため追加のコンテナを自前で運用する必要がありません。

認証方式はAPIキーとOAuth 2.1の2択です。

複数人で同じAgent Builderに繋ぐなら、OAuthはクライアント登録が1つで済みます。各人が個別に同意して自分の権限で動く接続を持ち、接続ごとに取り消せる点が共有キーとの違いです。

Serverlessでプロジェクトを横断検索するcross-project searchを連携済みなら、ツール呼び出しはMCP URLのスペースが持つデフォルトのスコープに従います。スペース名を付けないURLはデフォルトスペースの扱いです。この機能はServerlessで一般提供、Elastic Stackでは使えません。

APIキーに必要な権限

Agent BuilderのAPIキーには、インデックス権限に加えてKibanaのアプリケーション権限が要ります。公式の例ではfeature_agentBuilder.readとfeature_actions.readを付け、clusterにmonitor_inferenceを指定します。

POST /_security/api_key
{
  "name": "my-mcp-api-key",
  "expiration": "30d",
  "role_descriptors": {
    "mcp-access": {
      "cluster": ["monitor_inference"],
      "indices": [
        { "names": ["logs-*", "metrics-*"],
          "privileges": ["read", "view_index_metadata"] }
      ],
      "applications": [
        { "application": "kibana-.kibana",
          "privileges": ["feature_agentBuilder.read", "feature_actions.read"],
          "resources": ["space:default"] }
      ]
    }
  }
}

feature_agentBuilder.readが無いと、MCPエンドポイントへの接続は403 Forbiddenになります。有効期限は開発用なら1〜7日、本番用なら30〜90日とし、定期的に作り直すのが公式の目安です。

Claude Codeに登録する(claude mcp add)

Claude Codeにはclaude mcp addで登録します。Claude Codeのドキュメントでは、サーバー名を先に置き、実行するコマンドは--の後ろに書く形が示されています。現行のDockerサーバーは次のとおりです。

claude mcp add elasticsearch \
  -e ES_URL=https://<host>:9200 -e ES_API_KEY=<api-key> \
  -- docker run -i --rm -e ES_URL -e ES_API_KEY \
  docker.elastic.co/mcp/elasticsearch stdio

--scope projectを付けて登録すると、.mcp.jsonにcommandがdocker、argsがrun・-i・--rm・-e・ES_URL…の配列に分かれて書かれます。envにはAPIキーが平文で入ります。Gitで共有するprojectスコープに実キーを置かず、既定のlocalスコープで登録する選択肢があります。

つまずきやすいのは-eの位置です。-eは値を複数取るオプションなので、サーバー名を-eの後ろに置くと名前まで環境変数として読まれます。結果はInvalid environment variable format: elasticsearch, environment variables should be added as: -e KEY1=value1 -e KEY2=value2というエラーです。

Agent Builder側はHTTPのMCPサーバーなので、コンテナは要りません。ヘッダーにAPIキーを渡します。

claude mcp add --transport http kibana-agent-builder \
  https://<kibana-url>/api/agent_builder/mcp \
  -H "Authorization: ApiKey <api-key>"

.mcp.jsonにはtypeがhttp、urlがエンドポイント、headersにAuthorizationという形で入ります。Elasticのドキュメントはnpx mcp-remoteを挟む設定例も載せていますが、Claude CodeはHTTPを直接話せるので橋渡しは要りません。登録後の使い方全般はClaude Codeの全体像にあります。

切り替えは、新旧を並べて動かしてから旧側を外す順が安全です。

現行サーバーとAgent Builderの違い

同じ「ElasticsearchをMCP経由でClaudeから触る」でも、扱える範囲が異なります。

分析基盤をMCPからClaudeに繋ぐ構成は、ClickHouse MCPサーバー、DuckDB / MotherDuck MCPサーバー、PostgreSQL MCPサーバーでも扱っています。接続先ごとの認証や配布形態の違いを比べるときの材料になります。

セキュリティと運用の注意点

現行サーバーの認証情報はコンテナに渡す環境変数としてのみ保持され、ディスクへの永続化やログ出力はされません。本番でAPIキーを直書きせず、AWS Secrets ManagerやSystems Manager Parameter Storeのようなシークレット管理サービス経由で注入する運用が推奨されています。APIキーには読み取り専用・対象インデックス限定の最小権限を与え、30〜90日ごとにローテーションするのが基本です。この考え方はAgent Builderでも同じで、APIキー認証ではキーの権限がそのままMCP経由の操作範囲になります。

通信経路の暗号化は、ES_URLをhttps://で指定していればMCPサーバーとElasticsearch間もHTTPS化されます。保存データの暗号化はコンテナ側では扱わず、Elasticsearchクラスター自体の暗号化設定に委ねられます。コンテナはデータをローカルに保持しないため、暗号化の責任範囲はクラスター側だけに絞って考えられます。

よくあるつまずき

• Agent Builderに繋ぐと403になる: APIキーにfeature_agentBuilder.readのKibanaアプリケーション権限が無い。インデックス権限だけでは通らない
• claude mcp addが環境変数の形式エラーで止まる: サーバー名を-eの後ろに書いている。名前を先に置き、コマンドは--の後ろに回す
• SSL証明書エラーで接続できない: 開発・検証環境限定でES_SSL_SKIP_VERIFY=trueを使えるが、本番クラスターでは証明書を正しく設定するのが前提
• v0.3.1からv0.4.0に上げたら設定が通らない: 0.4.0で設定方法が変わっている。移行時はREADMEの該当バージョンの手順に必ず読み替える
• Agent BuilderでOAuthの接続が切れる: 30日以上使わなかった接続は新しい接続が必要になり、再認可で戻る

まとめ

新しく繋ぐなら、Kibana組み込みで追加のコンテナが要らないAgent Builderのエンドポイントが基本線です。既存のDockerサーバーは5ツールのまま動き続けますが、受けられるのは重大なセキュリティ更新だけなので、Elastic 9.3以降(9.2はプレビュー)かServerlessに移れる時期に合わせて切り替えを決められます。