Allows exploration and search of OpenSearch clusters, providing tools for indexing, querying, and cluster management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-opensearch search logs for errors in the last hour"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Read-only MCP server for exploring and searching OpenSearch 2 clusters. Ideal for log analysis, index exploration, and query execution.
Tool | Description |
| Check connectivity — returns cluster name and version |
| Cluster health status (green/yellow/red), node and shard counts |
| List indices with health, doc count, and size. Optional pattern filter |
| Show field types and structure for an index |
| Execute queries using OpenSearch Query DSL (JSON) |
| Count documents matching an optional query |
| List all index aliases |
| Retrieve a specific document by ID |
Related MCP server: openobserve-community-mcp
Build the extension package:
npx @anthropic-ai/mcpb pack .In Claude Desktop, go to Settings → Extensions and upload mcpopensearch.mcpb.
Configure via the UI:
OpenSearch URL — e.g. http://your-opensearch:9200
Username / Password — optional, for basic auth
Add to your .claude/settings.json:
{
"mcpServers": {
"opensearch": {
"command": "uv",
"args": ["--directory", "/path/to/mcpopensearch", "run", "server.py"],
"env": {
"OPENSEARCH_URL": "http://localhost:9200",
"OPENSEARCH_USERNAME": "",
"OPENSEARCH_PASSWORD": ""
}
}
}
}Variable | Default | Description |
|
| OpenSearch cluster URL |
| (none) | Basic auth username |
| (none) | Basic auth password |
Search for errors in the last hour:
{
"query": {
"bool": {
"must": [
{"match": {"level": "ERROR"}},
{"range": {"@timestamp": {"gte": "now-1h"}}}
]
}
},
"sort": [{"@timestamp": "desc"}]
}Count documents by status code:
{
"query": {"match_all": {}},
"aggs": {"status_codes": {"terms": {"field": "response_code"}}}
}MIT
Get the cluster health status including node count, shard info, and overall status (green/yellow/red).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden and does indicate a read-only status retrieval plus the output categories. However, it does not mention error behavior, authentication needs, or the meaning of the status values, so transparency is adequate but limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, tight sentence that front-loads the action and resource before listing the key outputs. Every word adds value and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless health-check tool with an output schema available, the description is complete enough for an agent to select and invoke it correctly. It covers the purpose and the main returned categories without unnecessary detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter documentation burden; the 0-parameter baseline applies. The description appropriately says nothing about parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get the cluster health status' and lists the exact returned content (node count, shard info, overall status). This makes it clearly distinguishable from sibling tools like ping or list_indices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but gives no guidance on when to prefer it over sibling tools such as ping or list_aliases. No exclusions, prerequisites, or alternative conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count documents in an index, optionally filtered by a query.
Args: index: Index name or pattern (e.g. 'logs-*'). query_body: Optional JSON string with a query filter (e.g. '{"query": {"match": {"level": "ERROR"}}}').
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | ||
| query_body | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It clearly states that this is a count operation, accepts index patterns like 'logs-*', and treats query_body as an optional JSON query filter. Error behavior and edge cases are not covered, but the simple read-only nature of the operation is sufficiently disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear summary line followed by two terse argument explanations, each with a useful example. There is no filler, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter count operation with an output schema present, both inputs are fully explained and the behavior is clear. The main missing element is explicit guidance about when to choose this over search, but that is more of a usage-guideline concern than a completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. The Args section defines index as a name or pattern with an example, and query_body as an optional JSON string with a concrete match example. This adds real semantic meaning well beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Count documents in an index,' and adds the optional query-filtering capability. This clearly distinguishes it from siblings like search (which retrieves documents) and list_indices (which lists indices), so an agent knows exactly what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The counting use case is clear, but the description never explicitly tells an agent when to prefer this tool over search or another sibling. The guidance is implied by 'optionally filtered by a query,' but there are no stated exclusions or alternative-routing hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific document by its ID.
Args: index: Name of the index containing the document. doc_id: The document ID.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | ||
| doc_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Retrieve,' which implies a read operation, but it does not mention what happens if the document doesn't exist, whether authentication is needed, or any other side effects or error behavior. This is minimal transparency for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear one-line purpose followed by a brief Args list. There is no redundant fluff, and the key information is front-loaded. It loses one point because the Args section is somewhat duplicative of the input schema, but it remains efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity and the presence of an output schema, the description covers the basic call contract. However, it lacks usage context relative to sibling tools and omits behavioral details such as missing-document handling. It is adequate for a simple read operation but not fully complete for an agent deciding when and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the bare schema. The Args section adds a little semantic value by clarifying that index is 'the index containing the document' and doc_id is 'The document ID.' However, this largely restates the parameter names and provides no constraints, format, or additional context, so the compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Retrieve a specific document by its ID.' The verb 'Retrieve' and the resource 'specific document' make the operation unambiguous. It also differentiates from siblings like search and count, which do not target a doc_id directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this tool when you know the document ID and want that specific document. However, it does not explicitly state when to prefer this over search, count, or get_index_mapping, and it offers no exclusions or alternative routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the field mapping (schema) for an index, showing all fields and their types.
Args: index: Name of the index (e.g. 'filebeat-2024.01.15' or 'logs-*').
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does add a behavioral detail—'showing all fields and their types'—and the parameter examples suggest support for wildcard index patterns ('logs-*'). However, it does not disclose edge-case behavior such as missing indices or multi-index expansion details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and front-loaded: the first sentence states the purpose, and the Args section directly supports the single parameter. There is no redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool, the description captures the core input and output semantics, especially with an output schema already present. The main gap is the lack of usage guidance and edge-case behavior, but the tool's simplicity keeps the description reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema's index parameter has no description, leaving 0% schema coverage. The description compensates fully by naming the parameter ('Name of the index') and providing two illustrative examples, including a wildcard pattern, which adds practical meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get the field mapping (schema) for an index' and adds what it returns, 'showing all fields and their types.' This clearly distinguishes it from siblings like get_document, search, and list_indices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to choose this tool over alternatives, nor does it mention any exclusions or prerequisites. It only describes the action and parameter, leaving the agent to infer appropriate usage from the purpose itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all index aliases in the cluster, showing which indices they point to.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It clearly communicates that the operation is a read-only listing across the entire cluster and reveals what information the result includes. It does not address edge cases like empty clusters or permissions, but for a zero-parameter list operation this is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the action, scope, and output in under fifteen words. Every word adds meaning and nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless tool with an output schema provided, the description is essentially complete: it names the resource (index aliases), scope (cluster), and result (target indices). It could name a sibling alternative or mention behavior when no aliases exist, but those are minor gaps for this simple operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics to document. The description appropriately focuses on the operation rather than inputs. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a concrete verb-resource pair ('List all index aliases in the cluster') and a clear result ('showing which indices they point to'). This distinguishes it from sibling tools like list_indices or get_index_mapping without relying on the tool name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool by mentioning aliases and cluster scope, but it never explicitly contrasts it with siblings or states when not to use it. An agent must infer the alternative from the sibling list (e.g., list_indices for indices).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List indices in the cluster with their health, doc count, and size.
Args: pattern: Optional index name pattern to filter (e.g. 'filebeat-', 'logs-').
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the behavioral disclosure burden. It clearly implies a read-only listing operation and states what information is returned, but it does not mention permissions, pagination, index-access restrictions, or the behavior when no pattern is supplied. This is adequate but not deeply transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with the core purpose stated in the first sentence. The parameter note is minimal, and every sentence adds useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and a separate output schema, the description is nearly complete. It covers the main purpose, the return fields, and the only parameter. The main gap is the absence of routing guidance against similar sibling tools, but this is a minor omission for such a low-complexity operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage and only provides the parameter name and default null. The description compensates fully by explaining that the pattern is optional, is an index name filter, and includes concrete wildcard examples ('filebeat-*', 'logs-*'), which adds meaningful guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a clear resource ('indices in the cluster'), and the exact returned information ('health, doc count, and size'). This distinguishes it from sibling tools like list_aliases, cluster_health, and search without needing to inspect their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as search, count, list_aliases, or get_index_mapping. There are no explicit conditions, exclusions, or references to sibling tools, so the agent must infer usage solely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check connectivity to the OpenSearch cluster. Returns cluster name and version.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the operation and return value but does not explicitly state that it is read-only or describe any error/timeout behavior. For a simple ping this is adequate but not highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no wasted words. It front-loads the action and includes the key return information, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters, no annotations, and an output schema present, the description only needs to convey the tool's purpose and what it returns. It does so completely, leaving no critical gaps for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter behavior to explain. Per the zero-parameter baseline, the description need not add parameter detail, and it appropriately includes return information instead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Check connectivity') and a clear resource ('OpenSearch cluster'), and it states what the tool returns. It is clearly distinct from siblings like search or get_document, though it does not explicitly differentiate itself from cluster_health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is clear: use this tool to verify connectivity to the OpenSearch cluster. No alternatives or exclusions are mentioned, but with zero parameters and a self-evident purpose, the context is sufficient for an agent to know when to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a read-only search query against an index using OpenSearch Query DSL.
The query_body must be a valid JSON string representing the query portion. Example: {"query": {"match": {"message": "error"}}, "sort": [{"@timestamp": "desc"}]}
Args: index: Index name or pattern to search (e.g. 'filebeat-*'). query_body: JSON string with the OpenSearch Query DSL body. size: Maximum number of results to return (default 20, max 100).
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| index | Yes | ||
| query_body | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the operation is read-only and states the size limit and default, which are useful behavioral traits. However, it does not describe the return format, pagination behavior, error conditions, or any additional side effects, leaving meaningful gaps given that no annotations are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: an opening one-sentence purpose, a necessary JSON constraint, and a clean Args block. No filler or redundant content is present, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential invocation details: parameters, formats, defaults, and constraints, and an output schema exists so return-value documentation is not required. It is slightly incomplete only because it does not guide the agent toward alternative sibling tools when appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero schema description coverage, the description fully compensates: it explains index naming with an example pattern, defines query_body as a valid JSON query string with an illustrative example, and documents size's default and maximum. Every parameter receives meaningful usage detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb (search), resource (an index), and mechanism (OpenSearch Query DSL), with a concrete example. However, it does not explicitly distinguish itself from siblings like count or get_document, which could also operate on indexes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as count, get_document, or the other index-level tools. The only contextual hint is 'read-only', which implies safe usage but does not explain when another tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0cluster_healthcountget_documentget_index_mappinglist_aliaseslist_indicespingsearchScored across 8 tools
Tools target distinct resources/actions: cluster health, index listing, mappings, search, count, aliases, and document retrieval. Ping and cluster_health both relate to health but are clearly differentiated, as are search and count; no tools appear to duplicate each other.
Names are consistently lowercase snake_case, but conventions vary: bare verbs (ping, search, count), list_* (list_indices, list_aliases), get_* (get_document, get_index_mapping), and one noun-phrase tool (cluster_health). This is readable but not a uniform verb_noun pattern.
Eight tools fit a focused OpenSearch query and observability server well. There is no bloat or redundancy, and each tool covers a meaningful operation.
The set covers health, index listing/mapping, search, count, aliases, and document retrieval, but lacks write operations and common admin reads like index settings or cluster/node stats. For a read-only observability tool it is workable, but as a general OpenSearch surface it has notable gaps.
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Federated commerce search across independent WooCommerce merchants. Keyless, read-only MCP server.
Read-only MCP server for the OrchestKit docs: full-text search + Markdown fetch. No auth.
Read-only MCP server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.
