Exposes OpenSearch Dashboards API to manage saved objects (e.g., dashboards), list tenants and index patterns, and perform searches like the Discover app for log querying.
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., "@opensearch-dashboard-mcp list dashboards"
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.
MCP server that exposes OpenSearch Dashboards to an LLM client over stdio. Read saved objects, list tenants and index patterns, and query logs like the Discover app — all through the Dashboards API, so it works even when the raw OpenSearch REST API isn't exposed.
uvx opensearch-dashboard-mcp(After publishing to PyPI. For local dev use uvx --from . opensearch-dashboard-mcp.)
Related MCP server: Kibana Dashboard Builder
Environment variables:
Variable | Default | Purpose |
|
| Base URL |
| — | Basic auth / session-login user |
| — | Basic auth / session-login password |
|
| Verify TLS certs |
| — | If set (e.g. |
| auto | Local port for the tunnel; a free port is picked when unset |
When SSH_PROXY_TO is set, the server spawns ssh -N -D <port> <host> before
serving and routes HTTP through the resulting socks5h:// proxy. DNS is resolved
on the remote side, so this reaches targets only visible from a remote network
(e.g. a VPN living inside a container). Requires key-based SSH auth (runs with
BatchMode=yes). The tunnel lives exactly as long as the server.
{
"mcpServers": {
"opensearch-dashboards": {
"command": "uvx",
"args": ["opensearch-dashboard-mcp"],
"env": {
"OPENSEARCH_DASHBOARDS_URL": "http://localhost:5601",
"OPENSEARCH_DASHBOARDS_USERNAME": "admin",
"OPENSEARCH_DASHBOARDS_PASSWORD": "admin"
}
}
}
}ping() — check connectivity + auth. Hits the security authinfo endpoint;
on a 401 with credentials set, performs a session login and re-checks.
Returns {connected, authenticated, user, tenants} or the error reason.
list_saved_objects(type_="dashboard", per_page=20, tenant=None) — saved
objects via saved_objects/_find, returned as compact {id, title, type}.
tenant selects the multi-tenancy tenant (name, "__user__" for the private
tenant, or None for the user default).
get_tenants() — multi-tenancy tenants via the security plugin config API,
as {name, description, reserved, hidden}.
get_index_patterns(per_page=50) — index patterns (saved objects of type
index-pattern), as {id, title, time_field}.
discover_search(index, query=None, time_from=None, time_to=None, time_field="@timestamp", size=10, fields=None, tenant=None)
— fetch documents like the Discover app through the internal search API
(/internal/search/opensearch). query is a Lucene query_string; time_from/
time_to filter a range (now-15m, ISO, …); fields trims _source to avoid
flooding context. Returns {index, total, count, hits}.
Multi-tenancy note: saved objects are stored per tenant. Discover available tenant
names with get_tenants, then pass one as tenant to the other tools.
uv sync --group dev
uv run opensearch-dashboard-mcp # starts on stdio; Ctrl-D to exit
uv run pytest # tests (add --cov for the 100% gate)Layout: config.py (env → Settings), client.py (async httpx wrapper),
tools.py (tool registrations), server.py (entry point + tunnel), tunnel.py
(SSH SOCKS5 tunnel). See CLAUDE.md for the architecture in depth.
Fetch documents like the Discover app.
Runs a search against an index pattern through the internal search API
that OpenSearch Dashboards' Discover uses (/internal/search/opensearch),
so it works even when the raw OpenSearch REST API is not exposed.
index: index-pattern glob, e.g. logs-api-*
(discover them via list_saved_objects with type_="index-pattern").
query: Lucene query_string, e.g. level:error AND service:api.
None matches everything.
time_from / time_to: range on time_field, e.g. now-15m /
now or an ISO timestamp. Both optional.
time_field: timestamp field to filter/sort on (default @timestamp).
size: max hits to return (default 10; keep small — these are logs).
fields: restrict _source to these fields to avoid flooding the
context. None returns the full document.
tenant: securitytenant header; usually unnecessary for raw data.
Returns {index, total, count, hits: [{_id, _index, _source}]} where
total is the full match count (may be an estimate for large indices).
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| index | Yes | ||
| query | No | ||
| fields | No | ||
| tenant | No | ||
| time_to | No | ||
| time_from | No | ||
| time_field | No | @timestamp |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden of behavioral disclosure. It explains the internal API endpoint, parameter semantics, and return format, including that 'total may be an estimate for large indices'. It does not cover rate limits or error handling, but for a search tool, the level of detail is commendable.
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 efficiently structured: a one-line purpose, then bullet-pointed parameter details, and a clear return format specification. At ~200 words, every sentence adds value with no fluff. It is front-loaded with the primary use case.
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 has 8 parameters (1 required) and an output schema exists, the description is still comprehensive. It explains each parameter's purpose and format, the return structure, and a usage caveat (total may be estimate). No gaps remain for effective use by an AI agent.
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. It adds rich meaning for all 8 parameters: index as glob pattern, query as Lucene query_string with None meaning match all, time_from/to with examples, time_field default, size with recommendation, fields for restriction, and tenant as optional header. This goes well 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 starts with 'Fetch documents like the Discover app', clearly stating the verb and resource. It distinguishes itself from siblings (no other search-like tool) by specifying it uses the internal search API that Dashboards' Discover uses, making its purpose unique and clear.
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 provides explicit usage context: 'works even when the raw OpenSearch REST API is not exposed'. It advises to keep size small and use fields to avoid flooding the context. While it does not list when not to use or explicitly name alternatives, the provided guidance is sufficient for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List index patterns configured in OpenSearch Dashboards.
Index patterns are saved objects of type index-pattern. Returns
{id, title, time_field} where title is the pattern glob
(e.g. logs-*) and time_field its time field, if any.
| Name | Required | Description | Default |
|---|---|---|---|
| per_page | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 that the tool returns {id, title, time_field} and gives an example of the title pattern, which adds behavioral context beyond the input schema. However, it does not explicitly state read-only behavior or any other side effects, but 'List' implies a safe read operation.
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 only two sentences, front-loaded with the purpose, and includes a concise code snippet for the return format. Every sentence is informative with no wasted words.
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 simplicity of the tool (list with one optional parameter and an output schema exists), the description covers the core purpose and return format adequately. It could mention that pagination is handled by the optional per_page parameter, but that is present in the schema. Overall, it is sufficiently complete for an agent to understand the tool's function.
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%, meaning the input schema has no descriptions for its single parameter (per_page). The tool description does not mention or explain the parameter at all, failing to add 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 clearly states the verb 'List' and resource 'index patterns configured in OpenSearch Dashboards.' It distinguishes itself from sibling tools like discover_search (which performs searches) and get_tenants (which retrieves tenants).
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 provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. It only states what it does without contextualizing its use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List multi-tenancy tenants configured in OpenSearch Dashboards.
Uses the security plugin config API (/api/v1/configuration/tenants),
which returns a map of tenant name -> metadata. Flattened here to a list
of {name, description, reserved, hidden}.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description adds details: uses specific API endpoint, flattens response to structured list with fields {name, description, reserved, hidden}. Clearly indicates read operation.
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?
Two sentences: first states purpose, second adds implementation detail and output shape. No wasted words, 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?
Zero parameters, so minimal complexity. Description fully covers what the tool does and its output structure. Output schema exists but description already provides key fields.
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?
No parameters, so no need for param descriptions. Description adds value by explaining output format and API source.
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?
Explicitly states it lists multi-tenancy tenants in OpenSearch Dashboards. Differentiates from siblings like discover_search and get_index_patterns by being tenant-specific.
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 explicit when-to-use or alternatives, but sibling tools are distinct enough that context is clear. Could be improved by noting it's for tenant management vs search/index operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List saved objects of a given type (dashboard, index-pattern, search, ...).
Calls the Dashboards saved_objects/_find API and returns a compact
list of {id, title, type} so the LLM is not flooded with raw fields.
Saved objects are stored per multi-tenancy tenant. tenant selects
which one to read via the securitytenant header:
a tenant name (e.g. "Developers Core", "Global")
"user" for the caller's private tenant
None (default) uses the user's configured default tenant
Use the get_tenants tool to discover available tenant names.
| Name | Required | Description | Default |
|---|---|---|---|
| type_ | No | dashboard | |
| tenant | No | ||
| per_page | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must cover behavioral aspects. It mentions the compact format to avoid flooding, but doesn't disclose read-only nature, side effects, or authentication needs, leaving gaps.
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?
Concise with clear structure: purpose, API call, output format, then tenant options. Slightly verbose with the tenant explanation, but overall efficient.
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?
Covers main behavior and tenant selection but omits explanation of the per_page parameter. Output schema exists, so return details may be covered there, but the description alone is incomplete for all parameters.
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 coverage is 0%, but the description explains type_ and tenant in detail. Per_page is not mentioned, so 2 of 3 parameters are covered, adding value 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 clearly states the verb 'List' and resource 'saved objects', with examples of types. It distinguishes from siblings by focusing on listing by type, unlike discover_search or get_index_patterns.
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?
Provides guidance on selecting tenant and suggests using get_tenants to discover tenant names. However, it does not explicitly contrast with siblings or mention when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check OpenSearch Dashboards connectivity and authenticate.
Hits the security authinfo endpoint. If unauthenticated (HTTP 401) and credentials are configured, performs a session login and re-checks. Reports {connected, authenticated, user, tenants} or the error reason.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description fully carries the burden. It discloses the endpoint hit, the authentication flow (session login on 401), and the returned fields or error reason. This provides comprehensive behavioral context.
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 (two sentences) and front-loaded with the main purpose. It could be slightly more structured, but it is efficient and 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?
Given the tool has no parameters and an output schema exists, the description covers all necessary context: connectivity check, authentication handling, and return value structure (connected, authenticated, user, tenants, or error).
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 no parameters and 100% schema coverage, the description adds no parameter details, which is appropriate. It adds context on the tool's action and output, meeting the baseline expectation for zero-parameter tools.
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 verb 'Check' and the resource 'OpenSearch Dashboards connectivity and authenticate'. It distinguishes the tool from siblings like discover_search and get_tenants, which serve different purposes.
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?
It explicitly states when to use (to check connectivity and authenticate) but does not provide when-not-to or alternative tools. However, sibling tools have distinct functions, so the context is sufficient.
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.0discover_searchget_index_patternsget_tenantslist_saved_objectspingScored across 5 tools
Each tool targets a distinct resource or action: search, index patterns, tenants, saved objects, and connectivity. No overlap in purpose.
All tool names follow a consistent verb_noun pattern (e.g., discover_search, get_index_patterns), and 'ping' is a standard imperative verb, fitting the pattern.
5 tools is well-scoped for a dashboard interaction server, covering essential query and listing operations without being overly numerous.
Covers core read operations (search, list index patterns, tenants, saved objects) but lacks write operations (create/update/delete) and direct retrieval of saved object details, which are minor gaps for a query-focused tool.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
Discover Frontier inference capabilities and read sanitized usage through read-only tools.
Access Oi Contexts, Workflows, Skills, Guardrails, Connections, and reporting tools.
