OpenSearch MCP server: nine core tools, filters and clusters

OpenSearch deliberately keeps its tool count low, including a generic endpoint tool whose cluster URL an agent can supply.

Last verified 1 September 2026 · from The OpenSearch project's repository, its documentation and the server's own tools/list response

This page is one of 90 in a directory of monitoring and developer tools. Each page checks what an AI coding agent can get out of the tool through its MCP server, the connector that lets the agent query the tool directly.

What is the OpenSearch MCP server?

It is the OpenSearch project's server for the Model Context Protocol. The agent gains tools for listing indices, reading mappings, searching, and checking cluster health.

There are two official surfaces. The standalone server runs as a Python process you install. The ML Commons MCP server is built into OpenSearch itself, introduced in 3.0, and is a feature of the cluster rather than a package.

Tools beyond the core nine exist but are off by default, grouped into categories such as search_relevance and skills, enabled through OPENSEARCH_ENABLED_CATEGORIES or a config file.

OpenSearch's standalone server starts with nine core tools, including one that can call any OpenSearch endpoint. Its purpose is log and metric investigation, rather than code changes, releases, agent traces or cost records.

In practice, OpenSearch answers questions you can express as a query against an index, plus basic cluster health. An agent connected here can search logs, read a mapping and check whether shards are healthy. It cannot read an alert or a dashboard through the core tools, so this is a query tool rather than an observability platform.

What can an AI agent do with OpenSearch?

The last row is the design decision that shapes this connector. Rather than one tool per endpoint, OpenSearch ships one tool for all of them, which keeps the tool list small and moves the surface area into a single call.

What connecting costs before the first question

A context window is the amount of text a model can hold at once, and connecting uses some of it before the agent asks anything. Every tool the server registers sends its name, description and input schema to the model when the session starts. The tool list is charged whether or not a single tool is called.

OpenSearch is among the cheapest connectors measured in this guide, and the only one that is cheap by design rather than by being small. GenericOpenSearchApiTool replaces what would otherwise be dozens of endpoint-specific tools, and the optional categories stay off until you name them.

Encodings: GPT-5.6, GPT-5.5 o200k_base; GPT-4, GPT-3.5 cl100k_base; Claude Haiku 4.5 to Opus 5 count_tokens. Counted 21 August 2026 from tools/list on opensearch-mcp-server-py, run locally with a placeholder URL and credentials.

Registration is static, so no OpenSearch cluster was involved. Figures cover name, description and input schema, for the core tools only. The two models in column one share the o200k_base encoding, so they get one count. The spread is formatting, about 49%. Reasoning tokens are output, spent per request. The tool list is input, charged once at connection.

The Claude figures are measured rather than encoded. Anthropic publishes no local tokenizer, so the definitions were sent to the API's count_tokens endpoint and a no-tools baseline subtracted. The range covers two tokenizer generations rather than two serializations. Haiku 4.5 and Opus 4.6 sit at the low end, Opus 5 and Sonnet 5 at the high end. The gap between them is about a fifth.

OpenSearch MCP server limits: where answers come back incomplete

OpenSearch documents the limits below, and the first two follow from its generic-tool design.

How to configure OpenSearch MCP for agents

1. 1

   Give the server a read-only role

   GenericOpenSearchApiTool can call any endpoint, so the credential rather than the tool list is what bounds it.

2. 2

   Enable the SSRF guard if you use dynamic connections

   SSRF means server-side request forgery: an agent supplies a URL and the server fetches it. OPENSEARCH_SSRF_GUARD=true restricts caller-supplied URLs to public HTTPS addresses, and OPENSEARCH_ALLOW_AMBIENT_AWS_FALLBACK should stay off.

3. 3

   Enable only the categories you need

   OPENSEARCH_ENABLED_CATEGORIES turns on groups such as search_relevance and skills; each one adds tools and context cost.

4. 4

   Treat the built-in server as experimental

   ML Commons ships an MCP server inside OpenSearch 3.0. It avoids running a local process. OpenSearch's own documentation marks it experimental and states it is not recommended for use in a production environment. Use it to evaluate, not to deploy.

Paste this into your agent’s instructions

With one generic tool covering every endpoint, an agent can reach further than the tool names suggest. The block makes it state which endpoint it actually called.

When you answer using OpenSearch MCP tools, state:
- The index or indices you searched, and the time range.
- If you used GenericOpenSearchApiTool, the exact path and
  method you called.
- The cluster you queried, if dynamic connection parameters
  are enabled.
Never state that data does not exist. State that none was
returned under the constraints above.
Write your answer in ASD-STE100 Simplified Technical
English. Use short sentences with one idea in each.

Do you need the MCP server at all?

Frequently, yes. OpenSearch's REST API is fully documented, and GenericOpenSearchApiTool is itself close to calling the API directly with an extra layer.

The connector adds discovery. An agent that has ListIndexTool and IndexMappingTool can find out what exists before querying, which is the step that fails most often when an agent writes a query from memory.

The built-in ML Commons server is the other option, with a caveat OpenSearch states plainly: it is experimental and not recommended for production. It is a feature of the cluster rather than a process you run, which suits evaluation in environments where installing a local server is awkward.

Use the standalone server for anything running in production. Consider ML Commons only for evaluation, where running a local process is the obstacle and OpenSearch's experimental designation is acceptable.

OpenSearch MCP server setup

The package runs with uvx and needs OPENSEARCH_URL plus credentials: basic auth, or AWS signing through AWS_REGION and a profile.

Tool filtering is configured with OPENSEARCH_ENABLED_CATEGORIES and OPENSEARCH_DISABLED_CATEGORIES.

claude mcp add-json "opensearch" '{"command":"uvx",
  "args":["opensearch-mcp-server-py"],
  "env":{"OPENSEARCH_URL":"https://your-cluster:9200",
         "OPENSEARCH_USERNAME":"<user>",
         "OPENSEARCH_PASSWORD":"<password>"}}'

{"mcpServers":{"opensearch":{"command":"uvx",
  "args":["opensearch-mcp-server-py"],
  "env":{"OPENSEARCH_URL":"https://your-cluster:9200",
         "OPENSEARCH_USERNAME":"<user>",
         "OPENSEARCH_PASSWORD":"<password>"}}}}

[mcp_servers.opensearch]
command = "uvx"
args = ["opensearch-mcp-server-py"]
env = { OPENSEARCH_URL = "https://your-cluster:9200", OPENSEARCH_USERNAME = "<user>", OPENSEARCH_PASSWORD = "<password>" }

Every other client

Each block below is the configuration for one client, with the file path and the key that client expects.

{"mcpServers":{"opensearch":{"command":"uvx",
  "args":["opensearch-mcp-server-py"],
  "env":{"OPENSEARCH_URL":"https://your-cluster:9200","OPENSEARCH_USERNAME":"<user>","OPENSEARCH_PASSWORD":"<password>"}}}}

{"mcpServers":{"opensearch":{"command":"uvx",
  "args":["opensearch-mcp-server-py"],
  "env":{"OPENSEARCH_URL":"https://your-cluster:9200","OPENSEARCH_USERNAME":"<user>","OPENSEARCH_PASSWORD":"<password>"}}}}

{"servers":{"opensearch":{"command":"uvx",
  "args":["opensearch-mcp-server-py"],
  "env":{"OPENSEARCH_URL":"https://your-cluster:9200","OPENSEARCH_USERNAME":"<user>","OPENSEARCH_PASSWORD":"<password>"}}}}

{"mcpServers":{"opensearch":{"command":"uvx",
  "args":["opensearch-mcp-server-py"],
  "env":{"OPENSEARCH_URL":"https://your-cluster:9200","OPENSEARCH_USERNAME":"<user>","OPENSEARCH_PASSWORD":"<password>"}}}}

OPENSEARCH_URL=https://search-domain.eu-west-1.es.amazonaws.com \
AWS_REGION=eu-west-1 AWS_PROFILE=default \
uvx opensearch-mcp-server-py

OPENSEARCH_SSRF_GUARD=true \
OPENSEARCH_ALLOW_AMBIENT_AWS_FALLBACK=false \
uvx opensearch-mcp-server-py

Read-only access, permissions and security

• One default tool reaches every endpoint

  GenericOpenSearchApiTool takes a custom path, method and body, so it is bounded by the credential rather than by the tool list.

• Agents can supply the cluster URL

  Dynamic connection parameters exist so one agent can work across clusters. OPENSEARCH_SSRF_GUARD=true restricts those URLs to public HTTPS addresses.

• The server's own AWS credentials should stay out of this

  OPENSEARCH_ALLOW_AMBIENT_AWS_FALLBACK lets the server sign caller-supplied URLs with its own credentials, which extends the agent's reach to anything those credentials permit.

• Give it a read-only role

  The eight non-generic tools read, so a read-only OpenSearch role costs nothing except the generic tool's write capability.

Troubleshooting

The agent has no tool for something documented

Tools beyond the core nine ship disabled. Enable the category with OPENSEARCH_ENABLED_CATEGORIES, naming search_relevance or skills as needed.

401 or 403 on connect

Check the credential type. Basic auth uses OPENSEARCH_USERNAME and OPENSEARCH_PASSWORD; Amazon OpenSearch needs AWS_REGION and a profile so requests are signed.

An agent queried a cluster you did not expect

Dynamic connection parameters let the agent pass opensearch_url per call. Set OPENSEARCH_SSRF_GUARD=true, or avoid enabling dynamic connections.

A query returns nothing on an index you know has data

Have the agent call IndexMappingTool first. Field names come from the mapping, and a query written from memory fails as an empty result.

OpenSearch MCP server: Reference

What engineers report

The connector has 147 stars, is Apache 2.0 and was pushed on 20 August 2026. Public discussion is small, so the two issues below are the record rather than a sample of opinion.

“If the LLM uses the wrong field (e.g., response instead of response.keyword for an aggregation), OpenSearch does not raise an error, it simply returns an empty result.”

“Currently, the query appears to only support simple keyword searches, and semantic searches do not seem to be supported.”

Repository facts from the GitHub API, retrieved 21 August 2026. Tool counts come from the server's own tools/list response, not from the README.

Should you connect an agent to OpenSearch?

Yes. Best for OpenSearch teams giving the server a read-only role and enabling the SSRF guard.

Strongest fit

Teams running OpenSearch who want an agent to explore an unfamiliar cluster: what indices exist, what the fields are, what the logs say.

Main advantage

Very low context cost for real reach, achieved by one generic API tool instead of dozens of specific ones.

Main weakness

Core tools cover search and health only. Alerting and dashboards need categories you enable yourself.

Operational risk

The generic API tool reaches write endpoints, and dynamic connection parameters let an agent choose the cluster.

Frequently asked questions