# OpenSearch MCP Server: 2 Deployment Options and a Quick Tutorial OpenSearch MCP Server: 2 Deployment Options and a Quick Tutorial ================================================================ An MCP server is a software component that exposes external capabilities to AI applications through the Model Context Protocol (MCP) [Talk to a consultant](/contact-us/) - [ What is an MCP server? ](#sec-0) - [ Why OpenSearch Needs MCP ](#sec-1) - [ MCP Servers in OpenSearch ](#sec-2) - [ Tips from the expert ](#sec-3) - [ Tutorials: Getting Started with MCP in OpenSearch ](#sec-4) - [ How to Choose an OpenSearch MCP Server ](#sec-5) - [ Run Your OpenSearch MCP Server on NetApp Instaclustr Managed OpenSearch ](#sec-6) What is an MCP server? Why OpenSearch Needs MCP MCP Servers in OpenSearch Tips from the expert Tutorials: Getting Started with MCP in OpenSearch How to Choose an OpenSearch MCP Server Run Your OpenSearch MCP Server on NetApp Instaclustr Managed OpenSearch What is an MCP server? ---------------------- An MCP server is a software component that exposes external capabilities to AI applications through the Model Context Protocol (MCP). MCP is an open standard for connecting AI systems to external data sources, tools, and workflows, allowing an AI assistant to retrieve information, call approved functions, and interact with systems beyond the model’s built-in knowledge. In MCP’s client-server architecture, the AI application acts as the host, while an MCP client communicates with one or more MCP servers. Each server represents a system, service, or capability, such as a database, file repository, search engine, calendar, ticketing platform, codebase, or internal business application. Instead of building a custom integration for every AI model or tool, organizations can expose these systems through standardized MCP servers. MCP servers can provide three main types of capabilities. Tools allow the AI application to perform actions, such as querying an API, sending a message, creating a ticket, or running a search. Resources provide read-only context, such as documents, database schemas, files, logs, or knowledge base entries. Prompts provide reusable instruction templates that help the AI application complete specific workflows in a consistent way. *This is part of a series of articles about [OpenSearch](https://www.instaclustr.com/education/opensearch/complete-guide-to-opensearch-in-2025/)* Why OpenSearch Needs MCP ------------------------- ### Natural-Language Access to Search and Analytics Data OpenSearch is commonly used to store large volumes of operational, application, security, observability, and business data. However, accessing that data often requires users to understand index names, mappings, query DSL syntax, aggregations, filters, and cluster-specific conventions. This creates a barrier for analysts, engineers, support teams, and business users who know what they want to ask but do not know how to translate that question into an OpenSearch query. **How an MCP server helps:** An MCP server helps bridge this gap by allowing AI assistants and agent frameworks to interact with OpenSearch through natural-language workflows. A user can ask questions such as “What errors increased in the last hour?”, “Which services have the highest latency?”, or “Summarize failed login patterns by region,” and the AI application can use MCP tools to inspect indices, run searches, retrieve documents, or analyze results. This makes OpenSearch data more accessible without requiring every user to work directly with APIs or query syntax. ***Related content: Read our guide to*** [***OpenSearch semantic search***](https://www.instaclustr.com/education/opensearch/opensearch-semantic-search-the-basics-and-a-quick-tutorial-2026-guide/) ### Standardized AI Integration Without MCP, each AI assistant, agent framework, or internal application may require a custom integration with OpenSearch. These integrations often duplicate the same work: authentication, query execution, index discovery, response formatting, schema inspection, and permission handling. As AI adoption grows, this fragmented approach becomes harder to maintain and govern. **How an MCP server helps:** MCP provides a standardized interface between AI clients and OpenSearch capabilities. Instead of building one-off connectors for every AI tool, teams can expose OpenSearch through an MCP server that defines approved tools, resources, and interaction patterns. This makes it easier to connect OpenSearch to different AI environments while maintaining a consistent integration layer. It also supports a more modular architecture, where the AI application does not need to know the internal details of every backend system it interacts with. ### Better Use of Existing OpenSearch Deployments Many organizations already rely on OpenSearch for log analytics, observability, enterprise search, security investigation, and operational reporting. These deployments often contain high-value data, but much of that value remains locked behind dashboards, saved queries, or specialized workflows. MCP gives organizations a way to extend the usefulness of existing OpenSearch clusters without replacing their current search and analytics infrastructure. **How an MCP server helps:** By adding an MCP server, teams can make existing indices and search capabilities available to AI assistants in a controlled way. This can support use cases such as incident investigation, root-cause analysis, knowledge retrieval, customer support, compliance review, and operational reporting. Rather than moving data into a separate AI platform, organizations can let AI tools query OpenSearch where the data already resides, while preserving existing index structures, access controls, and operational investments. MCP Servers in OpenSearch -------------------------- ### 1. Built-In MCP Server Starting with OpenSearch 3.0, OpenSearch includes an experimental MCP server as part of the ML Commons plugin. Because the server is built into the cluster, there is no need to deploy or manage a separate MCP service. AI applications connect to a Server-Sent Events (SSE) endpoint, discover the available MCP tools, and invoke them using standard JSON arguments: - The built-in server exposes OpenSearch capabilities through standard MCP interfaces, allowing AI agents to perform search, analytics, and vector store operations without custom integration code. - Since it uses OpenSearch’s existing [security model](https://www.instaclustr.com/support/documentation/opensearch/using-opensearch/security-access-control/), authentication and access controls remain consistent with the rest of the cluster. - This provides a standardized way for AI frameworks such as LangChain, Amazon Bedrock, and other MCP-compatible clients to interact with OpenSearch while reducing operational overhead. ### 2. Standalone OpenSearch MCP Server For OpenSearch versions earlier than 3.0, MCP support is available through a standalone OpenSearch MCP server that runs outside the cluster. In this architecture, the AI application sends tool requests to the MCP server, which communicates with OpenSearch through its REST APIs, retrieves the requested data, formats the response, and returns it to the client. - Running the MCP server as a separate service provides greater deployment flexibility. - It can be upgraded independently of the OpenSearch cluster, supports both SSE and standard input/output (stdio) communication for different MCP clients. - It works with desktop and agent-based applications that connect to external MCP servers. - Because it communicates through the REST API, the standalone server can be used with multiple OpenSearch versions. - It is a practical option for organizations that are not yet running OpenSearch 3.0. Tips from the expert -------------------- ![Kassian Wren]()Kassian Wren Open Source Tech Evangelist Kassian Wren is an Open Source Technology Evangelist specializing in OpenSearch. They are known for their expertise in developing and promoting open-source technologies, and have contributed significantly to the OpenSearch community through talks, events, and educational content In my experience, here are tips that can help you better adapt to OpenSearch MCP servers: 1. **Expose task-oriented tools instead of generic search endpoints:** Rather than giving AI agents unrestricted search capabilities, create MCP tools around business tasks such as `find_failed_deployments`, `investigate_login_failures`, or `retrieve_customer_orders`. Narrow, purpose-built tools improve reliability, security, and the quality of generated responses. 2. **Validate and constrain generated queries server-side:** Never execute arbitrary Query DSL produced by an LLM. The MCP server should validate index access, reject expensive query types, enforce size limits, and inject mandatory tenant or security filters before forwarding requests to OpenSearch. 3. **Separate AI-facing indexes from operational indexes:** Many production indexes contain sensitive fields, noisy data, or mappings that aren’t suitable for conversational access. Consider exposing curated indexes or aliases specifically designed for AI workflows instead of your entire cluster. 4. **Optimize tools for token efficiency:** AI models don’t need thousands of search hits. MCP tools should summarize, aggregate, or paginate results before returning them to the model, reducing token usage while improving answer quality. 5. **Build multi-step investigation workflows into the server:** Instead of exposing only primitive operations like “search” and “list indexes,” create composite tools that automatically perform common investigation sequences, such as discovering relevant indexes, checking mappings, running filtered searches, and generating statistical summaries. Tutorials: Getting Started with MCP in OpenSearch -------------------------------------------------- ### Set Up the Built-in MCP Server in OpenSearch Starting with OpenSearch 3.0, the ML Commons plugin includes an experimental MCP server. After it is enabled, AI applications can connect using the Model Context Protocol (MCP), discover registered tools, and invoke them through a standard interface. **Step 1: Enable Experimental Streaming** The built-in MCP server uses Server-Sent Events (SSE), so you must first enable OpenSearch’s experimental streaming support. Follow the OpenSearch documentation to: - Install the `transport-reactor-netty4` plugin. - Enable the experimental streaming feature. **Step 2: Enable the MCP Server** Enable the experimental MCP server by updating the cluster settings: PUT /\_cluster/settings/ { "persistent": { "plugins.ml\_commons.mcp\_server\_enabled": "true" } } 1 2 3 4 5 6 PUT /\_cluster/settings/ { "persistent": { "plugins.ml\_commons.mcp\_server\_enabled": "true" } } Once this setting is applied, the MCP server becomes available, but it does not expose any tools until you register them. **Step 3: Register MCP Tools** The built-in server starts with no tools enabled. Register only the tools that you want AI clients to use. The following example registers two tools: - `ListIndexTool` for discovering indexes. - `SearchIndexTool` for running search queries. POST /\_plugins/\_ml/mcp/tools/\_register { "tools": \[ { "type": "ListIndexTool" }, { "type": "SearchIndexTool", "attributes": { "input\_schema": { "type": "object", "properties": { "input": { "index": { "type": "string", "description": "OpenSearch index name. for example: index1" }, "query": { "type": "object", "description": "...", "additionalProperties": false } } } }, "required": \[ "input" \], "strict": false } } \] } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 POST /\_plugins/\_ml/mcp/tools/\_register { "tools": \[ { "type": "ListIndexTool" }, { "type": "SearchIndexTool", "attributes": { "input\_schema": { "type": "object", "properties": { "input": { "index": { "type": "string", "description": "OpenSearch index name. for example: index1" }, "query": { "type": "object", "description": "...", "additionalProperties": false } } } }, "required": \[ "input" \], "strict": false } } \] } After the request completes successfully, both tools are available through the MCP server. **Step 4: Connect an MCP Client** The built-in server exposes its MCP endpoints under: /\_plugins/\_ml/mcp 1 /\_plugins/\_ml/mcp The server also exposes an internal message endpoint: /\_plugins/\_ml/mcp/sse/message?sessionId=... 1 /\_plugins/\_ml/mcp/sse/message?sessionId=... *Note: Starting with version 3.3, MCP Streamable HTTP Server API end points were introduced.* If you are using a Python MCP client, connect to: /\_plugins/\_ml/mcp/sse?append\_to\_base\_url=true 1 /\_plugins/\_ml/mcp/sse?append\_to\_base\_url=true **Step 5: Authenticate the Client** Include the appropriate authentication headers for your OpenSearch deployment. The following example uses HTTP Basic authentication with a LangChain MCP client: import base64 from langchain\_mcp\_adapters.client import MultiServerMCPClient username = "admin" password = "admin" cred = base64.b64encode( f"{username}:{password}".encode() ).decode() headers = { "Content-Type": "application/json", "Accept-Encoding": "identity", "Authorization": f"Basic {cred}" } client = MultiServerMCPClient({ "opensearch": { "url": "http://localhost:9200/\_plugins/\_ml/mcp/sse?append\_to\_base\_url=true", "transport": "sse", "headers": headers } }) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 import base64 from langchain\_mcp\_adapters.client import MultiServerMCPClient username = "admin" password = "admin" cred = base64.b64encode( f"{username}:{password}".encode() ).decode() headers = { "Content-Type": "application/json", "Accept-Encoding": "identity", "Authorization": f"Basic {cred}" } client = MultiServerMCPClient({ "opensearch": { "url": "http://localhost:9200/\_plugins/\_ml/mcp/sse?append\_to\_base\_url=true", "transport": "sse", "headers": headers } }) **Step 6: Build an AI Agent with LangChain** Once connected, the client automatically discovers the registered MCP tools. Those tools can then be passed to a LangChain agent, allowing the LLM to invoke OpenSearch operations when needed. The following example initializes an OpenAI model, discovers the available MCP tools, and asks the agent to list products stored in OpenSearch: import asyncio from dotenv import load\_dotenv from langchain.agents import create\_agent from langchain\_mcp\_adapters.client import MultiServerMCPClient from langchain\_openai import ChatOpenAI load\_dotenv() async def main() -> None: # OpenSearch 3.6 exposes MCP through Streamable HTTP. client = MultiServerMCPClient( { "opensearch": { "url": "http://localhost:9200/\_plugins/\_ml/mcp", "transport": "streamable\_http", "headers": { "Content-Type": "application/json", "Accept": "application/json, text/event-stream", }, } } ) # Discover the MCP tools registered in OpenSearch. tools = await client.get\_tools() model = ChatOpenAI( model="gpt-4o", temperature=0, ) agent = create\_agent( model=model, tools=tools, system\_prompt=( "You are an OpenSearch assistant. " "Use the available OpenSearch MCP tools to answer requests." ), ) result = await agent.ainvoke( { "messages": \[ { "role": "user", "content": "List all products stored in OpenSearch.", } \] } ) print(result\["messages"\]\[-1\].content) if \_\_name\_\_ == "\_\_main\_\_": asyncio.run(main()) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 import asyncio from dotenv import load\_dotenv from langchain.agents import create\_agent from langchain\_mcp\_adapters.client import MultiServerMCPClient from langchain\_openai import ChatOpenAI load\_dotenv() async def main() -> None: \# OpenSearch 3.6 exposes MCP through Streamable HTTP. client = MultiServerMCPClient( { "opensearch": { "url": "http://localhost:9200/\_plugins/\_ml/mcp", "transport": "streamable\_http", "headers": { "Content-Type": "application/json", "Accept": "application/json, text/event-stream", }, } } ) \# Discover the MCP tools registered in OpenSearch. tools = await client.get\_tools() model = ChatOpenAI( model="gpt-4o", temperature=0, ) agent = create\_agent( model=model, tools=tools, system\_prompt=( "You are an OpenSearch assistant. " "Use the available OpenSearch MCP tools to answer requests." ), ) result = await agent.ainvoke( { "messages": \[ { "role": "user", "content": "List all products stored in OpenSearch.", } \] } ) print(result\["messages"\]\[-1\].content) if \_\_name\_\_ == "\_\_main\_\_": asyncio.run(main()) **What Happens During Execution** When the agent receives the prompt, it determines which MCP tools it needs to answer the request. First, it invokes `ListIndexTool` to discover the available indexes in the cluster. After identifying the appropriate products index, it calls `SearchIndexTool` with a `match_all` query to retrieve the documents. A typical execution looks like this: > Entering new AgentExecutor chain... Invoking: `ListIndexTool` # Tool finds available indices including "products" Invoking: `SearchIndexTool` # Tool executes a match\_all query against the products index Final response: Here are the products listed in the OpenSearch index: 1. Product A: High-quality leather wallet 2. Product B: Eco-friendly bamboo toothbrush ... 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 > Entering new AgentExecutor chain... Invoking: `ListIndexTool` \# Tool finds available indices including "products" Invoking: `SearchIndexTool` \# Tool executes a match\_all query against the products index Final response: Here are the products listed in the OpenSearch index: 1. Product A: High-quality leather wallet 2. Product B: Eco-friendly bamboo toothbrush ... This example demonstrates the standard MCP workflow. Rather than generating OpenSearch requests itself, the AI agent discovers the available tools, selects the appropriate ones, executes them through the MCP server, and uses the returned data to answer the user’s question. ### Set Up the Standalone MCP Server in OpenSearch For OpenSearch versions that do not include the built-in MCP server, you can run the standalone OpenSearch MCP server as a separate Python service. The server connects to OpenSearch, exposes supported tools through MCP, and lets MCP-compatible clients query the cluster. #### **Step 1: Install the MCP Server Package** Install the official Python package from PyPI: pip install opensearch-mcp-server-py 1 pip install opensearch-mcp-server-py #### **Step 2: Configure Authentication** Set the environment variables that allow the MCP server to connect to your OpenSearch cluster. For basic authentication, use: export OPENSEARCH\_URL="<your\_opensearch\_domain\_url>" export OPENSEARCH\_USERNAME="<your\_opensearch\_domain\_username>" export OPENSEARCH\_PASSWORD="<your\_opensearch\_domain\_password>” 1 2 3 export OPENSEARCH\_URL="<your\_opensearch\_domain\_url>" export OPENSEARCH\_USERNAME="<your\_opensearch\_domain\_username>" export OPENSEARCH\_PASSWORD="<your\_opensearch\_domain\_password>” For AWS IAM role authentication, use: export OPENSEARCH\_URL="<your\_opensearch\_domain\_url>" export AWS\_REGION="<your\_aws\_region>" export AWS\_ACCESS\_KEY\_ID="<your\_aws\_access\_key>" export AWS\_SECRET\_ACCESS\_KEY="<your\_aws\_secret\_access\_key>" export AWS\_SESSION\_TOKEN="<your\_aws\_session\_token>" 1 2 3 4 5 export OPENSEARCH\_URL="<your\_opensearch\_domain\_url>" export AWS\_REGION="<your\_aws\_region>" export AWS\_ACCESS\_KEY\_ID="<your\_aws\_access\_key>" export AWS\_SECRET\_ACCESS\_KEY="<your\_aws\_secret\_access\_key>" export AWS\_SESSION\_TOKEN="<your\_aws\_session\_token>" #### **Step 3: Start the MCP Server** For clients that use the stdio protocol, such as Claude for Desktop, start the server with: python -m mcp\_server\_opensearch 1 python -m mcp\_server\_opensearch For clients that connect over SSE, start the server with: python -m mcp\_server\_opensearch --transport sse 1 python -m mcp\_server\_opensearch --transport sse The SSE transport runs on port `9900`. #### **Step 4: Use the Available Tools** The standalone server currently exposes these OpenSearch tools: - `ListIndexTool` lists all indexes in the cluster. - `IndexMappingTool` retrieves mapping and settings information for a specific index. - `SearchIndexTool` searches an index with an OpenSearch query. - `GetShardsTool` returns shard information from OpenSearch. #### **Step 5: Connect Claude for Desktop** Claude for Desktop supports MCP over stdio, so it can start and communicate with the OpenSearch MCP server directly. In Claude for Desktop, go to **Settings > Developer > Edit Config**. Add the OpenSearch MCP server to `claude_desktop_config.json`: { "mcpServers": { "opensearch-mcp-server": { "command": "uvx", "args": \[ "opensearch-mcp-server-py" \], "env": { "OPENSEARCH\_URL": "<your\_opensearch\_domain\_url>", "OPENSEARCH\_USERNAME": "<your\_opensearch\_domain\_username>", "OPENSEARCH\_PASSWORD": "<your\_opensearch\_domain\_password>", "AWS\_REGION": "<your\_aws\_region>", "AWS\_ACCESS\_KEY\_ID": "<your\_aws\_access\_key>", "AWS\_SECRET\_ACCESS\_KEY": "<your\_aws\_secret\_access\_key>", "AWS\_SESSION\_TOKEN": "<your\_aws\_session\_token>" } } } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 { "mcpServers": { "opensearch-mcp-server": { "command": "uvx", "args": \[ "opensearch-mcp-server-py" \], "env": { "OPENSEARCH\_URL": "<your\_opensearch\_domain\_url>", "OPENSEARCH\_USERNAME": "<your\_opensearch\_domain\_username>", "OPENSEARCH\_PASSWORD": "<your\_opensearch\_domain\_password>", "AWS\_REGION": "<your\_aws\_region>", "AWS\_ACCESS\_KEY\_ID": "<your\_aws\_access\_key>", "AWS\_SECRET\_ACCESS\_KEY": "<your\_aws\_secret\_access\_key>", "AWS\_SESSION\_TOKEN": "<your\_aws\_session\_token>" } } } } Use either basic authentication values or IAM values, depending on how your OpenSearch cluster is secured. After saving the configuration, Claude can discover the OpenSearch tools and use them to inspect indexes, retrieve mappings, run searches, and check shard information. ### Connecting to an External MCP Server OpenSearch can use external MCP servers in agentic workflows. This lets an OpenSearch agent call tools that run outside the cluster, such as tools for weather data, remote APIs, or other external services. OpenSearch supports MCP servers that use either the Server-Sent Events (SSE) protocol or the Streamable HTTP protocol. The `stdio` protocol is not supported for this workflow. #### **Prerequisites** Before creating an MCP connector, enable MCP support and define which MCP server URLs OpenSearch is allowed to call: PUT /\_cluster/settings/ { "persistent": { "plugins.ml\_commons.trusted\_connector\_endpoints\_regex": \[ "<mcp server url>" \], "plugins.ml\_commons.mcp\_connector\_enabled": "true" } } 1 2 3 4 5 6 7 8 9 PUT /\_cluster/settings/ { "persistent": { "plugins.ml\_commons.trusted\_connector\_endpoints\_regex": \[ "<mcp server url>" \], "plugins.ml\_commons.mcp\_connector\_enabled": "true" } } The `trusted_connector_endpoints_regex` setting is used as a security control. It restricts MCP connections to URLs that match the configured regex patterns. You also need a running MCP server that is reachable from your OpenSearch cluster. #### **Step 1: Create an MCP Connector** An MCP connector stores the endpoint, protocol, credentials, and headers used to connect OpenSearch to an external MCP server. To create a connector for an SSE-based MCP server, use: POST /\_plugins/\_ml/connectors/\_create { "name": "My MCP Connector", "description": "Connects to the external MCP server for weather tools", "version": 1, "protocol": "mcp\_sse", "url": "https://my-mcp-server.domain.com", "credential": { "mcp\_server\_key": "THE\_MCP\_SERVER\_API\_KEY" }, "parameters": { "sse\_endpoint": "/sse" }, "headers": { "Authorization": "Bearer ${credential.mcp\_server\_key}" } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 POST /\_plugins/\_ml/connectors/\_create { "name": "My MCP Connector", "description": "Connects to the external MCP server for weather tools", "version": 1, "protocol": "mcp\_sse", "url": "https://my-mcp-server.domain.com", "credential": { "mcp\_server\_key": "THE\_MCP\_SERVER\_API\_KEY" }, "parameters": { "sse\_endpoint": "/sse" }, "headers": { "Authorization": "Bearer ${credential.mcp\_server\_key}" } } For a Streamable HTTP MCP server, use `mcp_streamable_http`: POST /\_plugins/\_ml/connectors/\_create { "name": "My MCP Connector (Streamable HTTP)", "description": "Connects to the external MCP server using Streamable HTTP", "version": 1, "protocol": "mcp\_streamable\_http", "url": "https://my-mcp-server.domain.com", "credential": { "mcp\_server\_key": "THE\_MCP\_SERVER\_API\_KEY" }, "parameters": { "endpoint": "/\_plugins/\_ml/mcp" }, "headers": { "Authorization": "Bearer ${credential.mcp\_server\_key}" } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 POST /\_plugins/\_ml/connectors/\_create { "name": "My MCP Connector (Streamable HTTP)", "description": "Connects to the external MCP server using Streamable HTTP", "version": 1, "protocol": "mcp\_streamable\_http", "url": "https://my-mcp-server.domain.com", "credential": { "mcp\_server\_key": "THE\_MCP\_SERVER\_API\_KEY" }, "parameters": { "endpoint": "/\_plugins/\_ml/mcp" }, "headers": { "Authorization": "Bearer ${credential.mcp\_server\_key}" } } The response includes a connector ID: { "connector\_id": "NZ2W2ZUBZ\_3SyqdOvh2n" } 1 2 3 { "connector\_id": "NZ2W2ZUBZ\_3SyqdOvh2n" } Save this value. You will use it when registering the agent. #### **Step 2: Register an LLM** Next, register an externally hosted large language model using a connector. The following example registers an OpenAI chat model: POST /\_plugins/\_ml/models/\_register { "name": "My OpenAI model: gpt-4", "function\_name": "remote", "description": "Test model registration", "connector": { "name": "My OpenAI Connector: gpt-4", "description": "Connector for the OpenAI chat model", "version": 1, "protocol": "http", "parameters": { "model": "gpt-4o" }, "credential": { "openAI\_key": "<YOUR\_API\_KEY>" }, "actions": \[ { "action\_type": "predict", "method": "POST", "url": "https://api.openai.com/v1/chat/completions", "headers": { "Authorization": "Bearer ${credential.openAI\_key}" }, "request\_body": "{ \\"model\\": \\"${parameters.model}\\", \\"messages\\": \[{\\"role\\":\\"developer\\",\\"content\\":\\"${parameters.system\_instruction}\\"},${parameters.\_chat\_history:-}{\\"role\\":\\"user\\",\\"content\\":\\"${parameters.prompt}\\"}${parameters.\_interactions:-}\], \\"tools\\": \[${parameters.\_tools:-}\],\\"parallel\_tool\_calls\\":${parameters.parallel\_tool\_calls},\\"tool\_choice\\": \\"${parameters.tool\_choice}\\" }" } \] } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 POST /\_plugins/\_ml/models/\_register { "name": "My OpenAI model: gpt-4", "function\_name": "remote", "description": "Test model registration", "connector": { "name": "My OpenAI Connector: gpt-4", "description": "Connector for the OpenAI chat model", "version": 1, "protocol": "http", "parameters": { "model": "gpt-4o" }, "credential": { "openAI\_key": "<YOUR\_API\_KEY>" }, "actions": \[ { "action\_type": "predict", "method": "POST", "url": "https://api.openai.com/v1/chat/completions", "headers": { "Authorization": "Bearer ${credential.openAI\_key}" }, "request\_body": "{ \\"model\\": \\"${parameters.model}\\", \\"messages\\": \[{\\"role\\":\\"developer\\",\\"content\\":\\"${parameters.system\_instruction}\\"},${parameters.\_chat\_history:-}{\\"role\\":\\"user\\",\\"content\\":\\"${parameters.prompt}\\"}${parameters.\_interactions:-}\], \\"tools\\": \[${parameters.\_tools:-}\],\\"parallel\_tool\_calls\\":${parameters.parallel\_tool\_calls},\\"tool\_choice\\": \\"${parameters.tool\_choice}\\" }" } \] } } The response returns a task ID and model ID: { "task\_id": "K\_iQfpYBjoQOEoSHN3wU", "status": "CREATED", "model\_id": "LPiQfpYBjoQOEoSHN3zH" } 1 2 3 4 5 { "task\_id": "K\_iQfpYBjoQOEoSHN3wU", "status": "CREATED", "model\_id": "LPiQfpYBjoQOEoSHN3zH" } Use the task ID with the Get ML Task API to check the registration status. When the task state changes to `COMPLETED`, the model is ready. #### **Step 3: Register an Agent with MCP Tools** MCP tools can be used with `conversational` agents and `plan-execute-reflect` agents. To make external tools available to the agent, add one or more MCP connectors in the `parameters.mcp_connectors` array. You can also use `tool_filters` to control which tools are exposed to the agent. The following example registers a conversational agent. The external MCP server exposes weather tools, but the agent is only allowed to use the `get_alerts` tool because of the `^get_alerts$` filter: POST /\_plugins/\_ml/agents/\_register { "name": "Weather & Search Bot", "type": "conversational", "description": "Uses MCP to fetch forecasts and OpenSearch indices", "llm": { "model\_id": "<MODEL\_ID\_FROM\_STEP\_2>", "parameters": { "max\_iteration": 5, "system\_instruction": "You are a helpful assistant.", "prompt": "${parameters.question}" } }, "memory": { "type": "conversation\_index" }, "parameters": { "\_llm\_interface": "openai/v1/chat/completions", "mcp\_connectors": \[ { "mcp\_connector\_id": "<MCP\_CONNECTOR\_ID\_FROM\_STEP\_1>", "tool\_filters": \[ "^get\_alerts$" \] } \] }, "tools": \[ { "type": "ListIndexTool" }, { "type": "SearchIndexTool" } \], "app\_type": "os\_chat" } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 POST /\_plugins/\_ml/agents/\_register { "name": "Weather & Search Bot", "type": "conversational", "description": "Uses MCP to fetch forecasts and OpenSearch indices", "llm": { "model\_id": "<MODEL\_ID\_FROM\_STEP\_2>", "parameters": { "max\_iteration": 5, "system\_instruction": "You are a helpful assistant.", "prompt": "${parameters.question}" } }, "memory": { "type": "conversation\_index" }, "parameters": { "\_llm\_interface": "openai/v1/chat/completions", "mcp\_connectors": \[ { "mcp\_connector\_id": "<MCP\_CONNECTOR\_ID\_FROM\_STEP\_1>", "tool\_filters": \[ "^get\_alerts$" \] } \] }, "tools": \[ { "type": "ListIndexTool" }, { "type": "SearchIndexTool" } \], "app\_type": "os\_chat" } The response includes the agent ID: { "agent\_id": "LfiXfpYBjoQOEoSH93w7" } 1 2 3 { "agent\_id": "LfiXfpYBjoQOEoSH93w7" } Save this ID so you can execute the agent. #### **Step 4: Run the Agent** Invoke the agent with the Execute Agent API and pass the user question in the `parameters` object: POST /\_plugins/\_ml/agents/{Agent\_ID}/\_execute { "parameters": { "question": "Any weather alerts in Washington", "verbose": true } } 1 2 3 4 5 6 7 POST /\_plugins/\_ml/agents/{Agent\_ID}/\_execute { "parameters": { "question": "Any weather alerts in Washington", "verbose": true } } The agent can use both local OpenSearch tools and the selected tools from the external MCP server. In this example, it can call `ListIndexTool` and `SearchIndexTool` from OpenSearch, and `get_alerts` from the MCP server. A response can include the model’s tool call, the MCP tool output, and the final answer: { "inference\_results": \[ { "output": \[ { "name": "response", "result": "There is a Wind Advisory for the Kittitas Valley in Washington..." } \] } \] } 1 2 3 4 5 6 7 8 9 10 11 12 { "inference\_results": \[ { "output": \[ { "name": "response", "result": "There is a Wind Advisory for the Kittitas Valley in Washington..." } \] } \] } This setup lets OpenSearch agents combine built-in search tools with external MCP tools in the same workflow. The MCP connector controls how OpenSearch reaches the external server, while `tool_filters` control which remote tools the agent can use. How to Choose an OpenSearch MCP Server --------------------------------------- The right MCP deployment depends primarily on your OpenSearch version, operational requirements, and the AI clients you want to support. While both deployment options expose OpenSearch through the Model Context Protocol, they differ in how they are deployed, managed, and integrated into your environment. Consider the following when choosing between the built-in and standalone OpenSearch MCP server: - **OpenSearch version:** If you are running OpenSearch 3.0 or later, you can use the built-in MCP server. Earlier versions require the standalone MCP server. - **Deployment model:** The built-in server runs inside the OpenSearch cluster and does not require additional infrastructure. The standalone server runs as a separate service and communicates with OpenSearch through the REST API. - **Supported client protocols:** The built-in server currently uses Server-Sent Events (SSE). The standalone server supports both SSE and stdio, making it compatible with desktop applications such as Claude for Desktop. - **Operational flexibility:** The standalone server can be upgraded, configured, and scaled independently of the OpenSearch cluster. The built-in server is managed as part of the OpenSearch deployment. - **Security and authentication:** The built-in server uses OpenSearch’s existing authentication and authorization model. The standalone server authenticates to OpenSearch using configured credentials or AWS IAM, while AI clients authenticate to the MCP server itself. - **Tool customization:** The built-in server requires administrators to explicitly register the tools that AI clients can access. The standalone server exposes its supported tool set when it starts. - **Upgrade strategy:** If you want new MCP features without upgrading your OpenSearch cluster, the standalone server offers a more independent release cycle. If you prefer fewer moving parts, the built-in server reduces operational overhead. - **External tool integration:** If your goal is to let OpenSearch agents access tools hosted outside the cluster, use MCP connectors to integrate external MCP servers regardless of whether you use the built-in or standalone OpenSearch MCP server. Run Your OpenSearch MCP Server on NetApp Instaclustr Managed OpenSearch ----------------------------------------------------------------------- Whether you use the built-in MCP server introduced in OpenSearch 3.0 or connect a standalone server through the REST API, both approaches depend on a healthy, well-configured, and secure OpenSearch cluster underneath. NetApp Instaclustr Managed OpenSearch provides that foundation as a fully managed, 100% open source service, so your teams can focus on building AI-driven search and analytics workflows instead of operating the cluster themselves. The platform now runs OpenSearch 3.3, and it can be deployed in your own cloud account, in Instaclustr’s, or on-premises. **Key capabilities of NetApp Instaclustr Managed OpenSearch:** - **AI-powered search built in:** Deploy a pipeline to ingest, vectorize, and search your data, with integrated vector search and AI capabilities directly within OpenSearch to power semantic search, Retrieval-Augmented Generation (RAG), and chatbots. - **Enterprise-grade security and compliance:** Managed clusters come with enterprise-grade encryption for data at rest and in transit, strict access controls, constant monitoring, and compliance with SOC2, ISO27001, ISO27018, PCI-DSS, and HIPAA standards, keeping authentication consistent across your cluster. - **High availability and data protection:** Benefit from up to 99.999% availability SLA and up to 99% latency SLAs, built-in redundancy and automatic failover, hourly backups, and searchable snapshots that let you query snapshot data without a full restore. - **Fast, flexible deployment:** Spin up production-ready clusters in minutes using the console, API, or Terraform provider, scale dynamically to handle bursting demand, and run on AWS, GCP, Azure, on-prem, or hybrid environments. - **Plugin framework and dashboards:** Enable a range of OpenSearch plugins at any time through the console, API, or Terraform, and add an OpenSearch Dashboards node to visualize and navigate your data. - **24/7 expert support:** Get round-the-clock support from a team of seasoned OpenSearch professionals, backed by configurations tuned from years of operating tens of millions of node hours. Ready to give your AI agents a reliable, secure foundation for MCP-based search and analytics? Learn more about[ NetApp Instaclustr Managed OpenSearch](https://www.instaclustr.com/platform/managed-opensearch/). [ Add Instaclustr as a preferred source on Google ](https://google.com/preferences/source?q=instaclustr.com) ### Related content [12 Agentic AI Tools to Know in 2026: Front-End to Back-End](https://www.instaclustr.com/education/agentic-ai/12-agentic-ai-tools-to-know-in-2026-front-end-to-back-end/) [4 OpenSearch Hybrid Search Technique, Tutorial, and Best Practices](https://www.instaclustr.com/education/opensearch/4-opensearch-hybrid-search-technique-tutorial-and-best-practices/) [Top 7 Managed OpenSearch Services with Customizable Ingest Pipelines](https://www.instaclustr.com/education/opensearch/best-cloud-based-opensearch-services-top-5-solutions-in-2025/) [Best managed OpenSearch platforms: Top 6 solutions to know in 2026](https://www.instaclustr.com/education/opensearch/best-managed-opensearch-platforms-top-6-solutions-to-know-in-2026/) [Best open source vector database software: Top 10 in 2026](https://www.instaclustr.com/education/vector-database/best-open-source-vector-database-software-top-8-in-2026/) [Complete guide to OpenSearch in 2026](https://www.instaclustr.com/education/opensearch/complete-guide-to-opensearch-in-2025/) [Creating your first OpenSearch® cluster and pro tips for success](https://www.instaclustr.com/education/opensearch/creating-your-first-opensearch-cluster-and-pro-tips-for-success/) [Deploying OpenSearch® with the official Helm chart: Step by step](https://www.instaclustr.com/education/opensearch/deploying-opensearch-with-the-official-helm-chart-step-by-step/) [Getting started with OpenSearch®: 2 quick tutorials](https://www.instaclustr.com/education/opensearch/getting-started-with-opensearch-2-quick-tutorials/) [Opensearch for SIEM: The Basics and a Quick Tutorial](https://www.instaclustr.com/education/opensearch/opensearch-for-siem-the-basics-and-a-quick-tutorial/) [OpenSearch migration: 3 approaches and best practices](https://www.instaclustr.com/education/opensearch/opensearch-migration-3-approaches-and-best-practices/) [OpenSearch semantic search: The basics and a quick tutorial \[2026 guide\]](https://www.instaclustr.com/education/opensearch/opensearch-semantic-search-the-basics-and-a-quick-tutorial-2026-guide/) [OpenSearch Serverless: How it works, pricing, and a quick tutorial](https://www.instaclustr.com/education/opensearch/opensearch-serverless-how-it-works-pricing-and-a-quick-tutorial/) [OpenSearch vector search: The basics and a quick tutorial \[2026 guide\]](https://www.instaclustr.com/education/opensearch/opensearch-vector-search-the-basics-and-a-quick-tutorial-2026-guide/) [OpenSearch vs. Elasticsearch: Similarities and 6 key differences](https://www.instaclustr.com/education/opensearch/opensearch-vs-elasticsearch-similarities-and-6-key-differences/) [OpenSearch vs. Kibana: Similarities, Differences, and How to Choose](https://www.instaclustr.com/education/opensearch/opensearch-vs-kibana-similarities-differences-and-how-to-choose/) [OpenSearch® pricing for two managed service options](https://www.instaclustr.com/education/opensearch/opensearch-pricing-for-two-managed-service-options/) [pgvector Hybrid Search: Benefits, Use Cases, and Quick Tutorial](https://www.instaclustr.com/education/vector-database/pgvector-hybrid-search-benefits-use-cases-and-quick-tutorial/) [pgvector vs OpenSearch for vector databases: 5 differences and how to choose](https://www.instaclustr.com/education/vector-database/pgvector-vs-opensearch-for-vector-databases-5-differences-and-how-to-choose/) [pgvector vs Pinecone: 8 Key Differences and How to Choose](https://www.instaclustr.com/education/vector-database/pgvector-vs-pinecone-8-key-differences-and-how-to-choose/) [Running OpenSearch on Kubernetes: Quick start tutorial](https://www.instaclustr.com/education/opensearch/running-opensearch-on-kubernetes-quick-start-tutorial/) [Running OpenSearch with Docker: Tutorial and best practices](https://www.instaclustr.com/education/opensearch/running-opensearch-with-docker-tutorial-and-best-practices/) [Using OpenSearch for AI: The basics and a quick tutorial](https://www.instaclustr.com/education/opensearch/using-opensearch-for-ai-the-basics-and-a-quick-tutorial/) [Vector database AWS: Comparing service options and how to get started](https://www.instaclustr.com/education/vector-database/vector-database-aws-comparing-service-options-and-how-to-get-started/) ### Related content [ What is vector similarity search? Pros, cons, and 5 tips for success Vector similarity search is an information retrieval technique that matches data on semantic meaning rather than exact keyword ... ](https://www.instaclustr.com/education/vector-database/what-is-vector-similarity-search-pros-cons-and-5-tips-for-success/) [ What are managed database services and 7 key capabilities A managed database service (MDS) allows organizations to outsource the maintenance and management of database systems to a third-... ](https://www.instaclustr.com/education/data-architecture/what-are-managed-database-services-and-7-key-capabilities/) [ Vector search vs semantic search: 4 key differences and how to choose Vector search finds items in a dataset using vectors. Semantic search boosts accuracy by grasping searcher intent and term context... ](https://www.instaclustr.com/education/vector-database/vector-search-vs-semantic-search-4-key-differences-and-how-to-choose/) Spin up a cluster In minutes ------------------------------ [ Check it out ](/platform/)