Connect an AI agent to your OpenSearch cluster

OpenSearch ships its own MCP server inside the ML Commons plugin. Turning it on lets an agent search your indices, read mappings and run PPL against the data in the cluster, rather than being handed a query language and left to construct HTTP calls itself.

It needs OpenSearch 3.3.0 or later. Before that the plugin only has a Server-Sent Events endpoint, which ClusterNest clusters do not serve (on 3.2.0 it answers “The engine does not support HTTP streaming” even with the server on). It is off by default.

There are two ways to use it. The ClusterNest MCP connector can turn it on and run its tools for you, which works from any client, the Claude apps included. Or you can turn it on with two API calls and point a client of your own straight at it.

Through the ClusterNest MCP connector

An agent connected to the MCP connector needs no cluster password and no second connection. Its requests reach the cluster with a 15-minute token that carries your role in the organization, so a member with the Read role gets read-only access. The cluster needs the ClusterNest sign-in (the builtin auth source), which every new cluster has.

• enable_opensearch_cluster_mcp turns the server on and registers twelve read-only tools: ListIndexTool, IndexMappingTool, SearchIndexTool and SearchAroundDocumentTool for indices and documents; LogPatternTool, LogPatternAnalysisTool, DataDistributionTool and MetricChangeAnalysisTool for log and data analysis; and SearchAlertsTool, SearchMonitorsTool, SearchAnomalyDetectorsTool and SearchAnomalyResultsTool for alerting and anomaly detection. Each tool runs with the caller’s role, so one that the role cannot reach answers with the cluster’s own permission error. The call needs a role that may change the cluster’s settings, and it is safe to call again: it adds only the tools the cluster does not have yet. The connector’s tools need OpenSearch 3.6.0 or later.
• list_opensearch_cluster_mcp_tools and call_opensearch_cluster_mcp_tool list and run the cluster’s tools through the connector. This works from clients that cannot add a second MCP server or send a custom header, such as the Claude apps.
• get_opensearch_cluster_mcp_connection returns the URL and a fresh bearer token for a client of your own. Send the token as Authorization: Bearer <token> and call the tool again when it expires.

The cluster’s ip_allowlist applies to these calls too. A hosted client such as the Claude apps reaches the cluster from its provider’s addresses, so allowlist the provider’s published outbound ranges (Anthropic’s for Claude).

Set it up yourself

1. Enable the server

Use your cluster’s admin credentials:

curl -X PUT https://opensearch.example.com/_cluster/settings \
  -u "admin:$OPENSEARCH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"persistent": {"plugins.ml_commons.mcp_server_enabled": true}}'

The setting is persistent, so it survives restarts and version upgrades.

2. Register the tools it should expose

Nothing is exposed until you register it. Each entry is an ML Commons tool type, optionally with an input schema describing its parameters to the model:

curl -X POST https://opensearch.example.com/_plugins/_ml/mcp/tools/_register \
  -u "admin:$OPENSEARCH_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": [
      { "type": "ListIndexTool", "name": "ListIndexTool" },
      { "type": "IndexMappingTool", "name": "IndexMappingTool" },
      {
        "type": "SearchIndexTool",
        "name": "SearchOsIndex",
        "description": "Search an OpenSearch index by DSL query. Params: index (index name), query (DSL query object).",
        "attributes": {
          "input_schema": {
            "type": "object",
            "properties": {
              "index": { "type": "string", "description": "The index to search" },
              "query": { "type": "object", "description": "OpenSearch DSL query" }
            },
            "required": ["index", "query"]
          }
        }
      }
    ]
  }'

type and name are both required (registration is rejected without a name); the name is what the model calls the tool by. Other tool types worth registering depending on what the cluster is used for: PPLTool, SearchAlertsTool, SearchMonitorsTool, SearchAnomalyDetectorsTool, SearchAnomalyResultsTool.

Check what is registered with:

curl https://opensearch.example.com/_plugins/_ml/mcp/tools/_list \
  -u "admin:$OPENSEARCH_PASSWORD"

Registered tools are stored in a system index and synced to every node from OpenSearch 3.1.0, so this is a one-time call rather than something to repeat per node or after a restart. Registration is not idempotent: re-registering a name that already exists is rejected, so list first if you are scripting it. POST /_plugins/_ml/mcp/tools/_remove takes a list of names back off again.

3. Point a client at it

The endpoint is streamable HTTP at https://opensearch.example.com/_plugins/_ml/mcp.

Authentication is the cluster’s own, so the client needs an Authorization header carrying HTTP basic credentials. In Claude Code:

claude mcp add --transport http --scope user \
  --header "Authorization: Basic $(printf 'admin:%s' "$OPENSEARCH_PASSWORD" | base64)" \
  production-logs https://opensearch.example.com/_plugins/_ml/mcp

Other clients take the same URL and header in their own config format.

Two things to get right before this works from a laptop or a CI runner:

• The IP allowlist. Whatever runs the agent has to be inside the cluster’s ip_allowlist. A local agent means your own address, and an agent running somewhere else means that host’s address.
• The user the agent connects as. The tools run with exactly the permissions of those credentials. admin gives an agent the whole cluster, deletes included. For anything beyond trying it out, create an internal user with a read-only role over the indices it should see and connect with that instead.