Merge Unified's Elasticsearch integration Merge Agent Handler's Elasticsearch MCP server

Connect your AI Agents to Elasticsearch in minutes

Merge lets you securely connect your agents to Elasticsearch and thousands of tools instantly

Start building for free

Read docs

Elasticsearch

Learn more about Merge Agent Handler

Available tools

cat_indices

List indices with health, status, document counts, and store size via GET /_cat/indices. Filter by health and choose columns with h. This is the primary way to discover index names for other tools.

cat_health

Show a one-line cluster health summary via GET /cat/health (status, node and shard counts). Use clusterhealth for the full structured health document.

cat_nodes

List cluster nodes with resource usage (heap, CPU, load, role) via GET /_cat/nodes. Choose columns with h and sort with s.

cat_aliases

List index aliases and the indices they point to via GET /cat/aliases. Choose columns with h and sort with s. Use getaliases for a structured per-index view.

cat_shards

List shards with their index, state, document count, and node placement via GET /_cat/shards. Choose columns with h and sort with s.

cat_count

Show the total document count across the cluster via GET /_cat/count. Use the count tool for a per-index count with an optional query.

cluster_health

Retrieve the full cluster health document via GET /cluster/health (status, node counts, shard counts). Use cathealth for a one-line summary.

cluster_stats

Retrieve aggregate cluster statistics via GET /_cluster/stats (index, document, shard, and node totals).

get_cluster_settings

Retrieve persistent and transient cluster settings via GET /cluster/settings. Use updatecluster_settings to change them.

update_cluster_settings

Update persistent and/or transient cluster settings via PUT /cluster/settings. Overwrites the named settings. Use getcluster_settings to see current values first.

index_document

Index (create or overwrite) a document at a given ID with PUT /{index}/doc/{id}. Overwrites any existing document with that ID. Returns id and version for chaining to getdocument. Use cat_indices to find index names.

create_document

Create a new document at a given ID with POST /{index}/create/{id}. Fails with a conflict if the ID already exists (use indexdocument to overwrite). Returns id and version. Use cat_indices to find index names.

get_document

Retrieve a document and its metadata by ID with GET /{index}/doc/{id}. Returns found, version, and source. Use search or catindices to discover IDs and index names.

get_document_source

Retrieve only the stored source body of a document by ID with GET /{index}/source/{id}, without the surrounding metadata. Use getdocument when you also need version/found. Use search to discover IDs.

update_document

Partially update a document by ID with POST /{index}/update/{id}, using a partial doc merge, a script, or an upsert. Overwrites the targeted fields. Use search to discover IDs and catindices for index names.

delete_document

Delete a document by ID with DELETE /{index}/doc/{id}. Returns result 'deleted' or 'notfound'. Use search to discover IDs and cat_indices for index names.

bulk

Perform many index/create/update/delete actions in one request with POST /{index}/bulk. Pass operations as alternating action and source lines. Returns per-action items and an errors flag. Use catindices for index names.

mget_documents

Fetch multiple documents in one request with POST /{index}/mget, by ids or per-document docs specs. Returns one entry per requested document with found and source. Use cat_indices for index names.

delete_by_query

Delete all documents matching a Query DSL query with POST /{index}/deletebyquery. Returns totals of matched and deleted documents. Use search to preview the matching set first. Use catindices for index names.

update_by_query

Update all documents matching a query with POST /{index}/updatebyquery, applying an optional script. Returns totals of matched and updated documents. Use search to preview the set. Use catindices for index names.

reindex

Copy documents from one index to another with POST /reindex, given source and dest specs. Returns totals of created/updated documents. Create the destination index (createindex) first if it needs custom mappings.

get_term_vectors

Retrieve term vectors and term statistics for a document's fields with POST /{index}/termvectors/{id}. Useful for inspecting analysis and relevance. Use search to discover IDs and catindices for index names.

esql_query

Run an ES|QL query with POST /query. ES|QL is Elasticsearch's piped query language, e.g. 'FROM products | STATS count=COUNT(*) BY category'. Returns columns (name/type schema) and values (rows). Use catindices to find index names to query FROM.

create_index

Create a new index with PUT /{index}, optionally with mappings, settings, and aliases. Returns acknowledged. Fails if the index already exists. Use cat_indices to check existing names.

get_index

Retrieve an index's definition (aliases, mappings, settings) with GET /{index}, keyed by index name. Use cat_indices to list index names.

delete_index

Permanently delete an index and all its documents with DELETE /{index}. Returns acknowledged. Use cat_indices to list index names. This cannot be undone.

open_index

Open a closed index with POST /{index}/open so it accepts reads and writes again. Returns acknowledged. Use catindices to list index names.

close_index

Close an index with POST /{index}/close, blocking reads and writes until reopened. Returns acknowledged. Use openindex to reverse. Use cat_indices to list index names.

refresh_index

Refresh an index with POST /{index}/refresh to make recent writes searchable immediately. Returns shard statistics. Use catindices to list index names.

get_mapping

Retrieve an index's field mappings with GET /{index}/mapping, keyed by index name. Use this to discover field names and types before searching. Use catindices to list index names.

update_mapping

Add fields to an index's mapping or change its dynamic mode with PUT /{index}/mapping. You can add new fields but not change existing field types. Returns acknowledged. Use getmapping to see current fields. Use cat_indices for index names.

get_settings

Retrieve an index's settings (shards, replicas, refresh interval, etc.) with GET /{index}/settings, keyed by index name. Use catindices to list index names.

update_settings

Update an index's dynamic settings with PUT /{index}/settings, e.g. numberofreplicas or refreshinterval. Overwrites the named settings. Returns acknowledged. Use getsettings to see current values. Use catindices for index names.

add_alias

Add an alias to an index with PUT /{index}/alias/{name}, optionally filtered or as the write index. Returns acknowledged. Use catindices for index names and get_aliases to see current aliases.

delete_alias

Remove an alias from an index with DELETE /{index}/alias/{name}. Returns acknowledged. Use getaliases to list an index's aliases and cat_indices for index names.

get_aliases

Retrieve the aliases attached to an index with GET /{index}/alias, keyed by index name. Use cataliases for a flat cross-index view. Use cat_indices for index names.

analyze_text

Analyze text with POST /{index}/analyze to see the tokens an analyzer produces, by named analyzer or by field. Returns the token stream. Useful for debugging search behavior. Use catindices for index names.

list_index_templates

List all composable index templates with GET /indextemplate. Returns each template's name and body (index patterns, settings, mappings). Use this to discover template names to pass to getindextemplate or deleteindextemplate.

get_index_template

Retrieve a composable index template by name with GET /indextemplate/{name}, including its index patterns, settings, and mappings. Use listindextemplates to discover names, or putindextemplate to create one.

put_index_template

Create or replace a composable index template with PUT /indextemplate/{name}, applying its settings/mappings to indices matching index_patterns. Overwrites any template with that name. Returns acknowledged.

delete_index_template

Delete a composable index template by name with DELETE /indextemplate/{name}. Returns acknowledged. Use getindextemplate to confirm it exists first.

get_index_stats

Retrieve statistics for an index (document counts, store size, operation counters) with GET /{index}/stats. Limit to specific stat groups with metric. Use catindices for index names.

get_cluster_info

Retrieve the cluster info document via GET / — the node name, cluster name, cluster UUID, and Elasticsearch version. A lightweight way to confirm connectivity and check the server version.

list_pipelines

List all ingest pipelines via GET /ingest/pipeline. The response is keyed by pipeline ID, each with its processors. Use this to discover pipeline IDs to pass to indexdocument/bulk's pipeline param or to getpipeline/deletepipeline.

get_pipeline

Retrieve an ingest pipeline definition by ID via GET /ingest/pipeline/{id}. The response is keyed by pipeline ID and lists its processors. Use listpipelines to discover IDs, or put_pipeline to create one.

put_pipeline

Create or replace an ingest pipeline via PUT /ingest/pipeline/{id} with an ordered list of processors. Overwrites any existing pipeline with that ID. Reference the pipeline by ID in indexdocument/bulk's pipeline param.

delete_pipeline

Delete an ingest pipeline by ID via DELETE /ingest/pipeline/{id}. Use getpipeline to confirm it exists first.

search

Run a search with POST /{index}/search using the Query DSL, with size/from or searchafter pagination, sort, aggregations, and source filtering. For deep/consistent pagination, open a point-in-time with openpointintime, pass it as pit, and page with searchafter. Returns the full hits envelope (took, shards, hits.total, hits.hits with source). Use catindices for index names.

count

Count documents matching an optional Lucene query with GET /{index}/count. Returns the count and shard statistics. Pass q to narrow, e.g. 'category:electronics'. Use catindices for index names.

multi_search

Run several searches in one request with POST /{index}/msearch. Pass searches as alternating header and body objects. Returns one response per sub-search, each with its own hits envelope. Use catindices for index names.

get_field_caps

Describe which indices a field exists in and its search/aggregation capabilities with POST /{index}/fieldcaps. Pass fields (a name, list, or '*'). Use this to discover queryable/aggregatable fields before building a search. Use cat_indices for index names.

explain_document

Explain whether and why a specific document matches a query with POST /{index}/explain/{id}, returning the relevance score breakdown. Use search to discover IDs and catindices for index names.

terms_enum

Enumerate matching terms in a keyword field with POST /{index}/termsenum, optionally filtered by a prefix string. Useful for autocomplete. Use getfieldcaps to find keyword fields and cat_indices for index names.

open_point_in_time

Open a point-in-time with POST /{index}/pit to run consistent paginated searches against a fixed view. keepalive is required (e.g. '1m'). Returns a PIT id; pass it to closepointintime when done. Use catindices for index names.

close_point_in_time

Close a point-in-time context with DELETE /pit to free its resources. Pass the id returned by openpointintime. Returns succeeded and the number of contexts freed.

list_tasks

List running tasks across the cluster via GET /tasks, grouped by node. Filter by actions pattern. Use this to discover task IDs for gettask and canceltask (e.g. long-running reindex/updateby_query jobs).

get_task

Retrieve the status and result of a single task via GET /tasks/{taskid}. Use listtasks to discover task IDs. Set waitfor_completion to block until the task finishes.

cancel_task

Cancel a running, cancellable task via POST /tasks/{taskid}/cancel. Use listtasks to discover task IDs. Returns the remaining tasks per node.

validate_credential

Validate the configured Elasticsearch API key and deployment endpoint by calling the cluster info endpoint (GET /, requires cluster monitor privilege). Returns success true/false and distinguishes invalid credentials from insufficient privileges.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}