Connecting an MCP client to an OpenSearch cluster

Follow this tutorial to set up an MCP connection to an OpenSearch cluster: enable the built-in MCP server, register tools, and add the server to the client configuration.

To set up a connection:

1. Start the MCP server.
2. Register tools.
3. Prepare a Basic token.
4. Add the MCP server to the client configuration.
5. Test the connection.

If you no longer need the resources you created, delete them.

Required paid resourcesRequired paid resources

The support cost for this solution includes:

• Managed Service for OpenSearch cluster: use of computing resources, storage and backup size (see Managed Service for OpenSearch pricing).
• Public IP addresses if public access is enabled for cluster hosts (see Yandex Virtual Private Cloud pricing).

Getting startedGetting started

1. Set up your infrastructure:

   Manually

   Using Terraform

   1. Create a Managed Service for OpenSearch cluster of your preferred configuration with public access to any host group.

      Note

      Public access to cluster hosts is required if you plan to connect to the cluster via the internet. This connection option is simpler and is recommended for the purposes of this guide. You can connect to non-public hosts as well but only from Yandex Cloud virtual machines located in the same cloud network as the cluster.

   2. If there are security groups in your cluster, make sure they are configured correctly and allow connections to the Managed Service for OpenSearch cluster.

   1. If you do not have Terraform yet, install it.

   2. Get the authentication credentials. You can add them to environment variables or specify them later in the provider configuration file.

   3. Configure and initialize a provider. There is no need to create a provider configuration file manually, you can download it.

   4. Place the configuration file in a separate working directory and specify the parameter values. If you did not add the authentication credentials to environment variables, specify them in the configuration file.

   5. Download the opensearch-mcp.tf configuration file to the same working directory. This file describes:

      • Network.
      • Subnet.
      • Security group and rules for connection to a Managed Service for OpenSearch cluster.
      • Managed Service for OpenSearch cluster.

   6. In the opensearch-mcp.tf file, specify the following variables:

      • version: OpenSearch version.
      • admin_password: OpenSearch admin password.

   7. Make sure the Terraform configuration files are correct using this command:

      terraform validate
      

      Terraform will display any configuration errors detected in your files.

   8. Create the required infrastructure:

      1. Run this command to view the planned changes:

         terraform plan
         

         If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

      2. If everything looks correct, apply the changes:

         1. Run this command:

            terraform apply
            

         2. Confirm updating the resources.

         3. Wait for the operation to complete.

      All the required resources will be created in the specified folder. You can check resource availability and their settings in the management console.

2. Install an SSL certificate.

3. Check the connection to the cluster using cURL:

   curl \
       --user admin:<password> \
       --cacert ~/.opensearch/root.crt \
       --request GET 'https://<FQDN_of_OpenSearch_host_with_public_access>:9200/'
   

   You can get the host FQDN with the list of hosts in the cluster.

   If the connection is successful, you will see a message like this:

   {
     "name" : "....mdb.yandexcloud.net",
     "cluster_name" : "...",
     "cluster_uuid" : "...",
     "version" : {
     "distribution" : "opensearch",
     ...
     },
     "tagline" : "The OpenSearch Project: https://opensearch.org/"
   }
   

4. Create a separate user for the MCP client.

   You can create an internal user either via OpenSearch Dashboards or via the Security REST API.

   OpenSearch Dashboards

   REST API

   1. Connect to OpenSearch Dashboards as admin.

   2. In the left-hand menu, select OpenSearch Plugins → Security.

   3. In the left-hand panel, select Internal users and click Create internal user.

   4. Enter a username, e.g., mcp-client, and password.

   5. Click Submit.

   6. Assign the ml_full_access role to the user:

      1. In the left-hand panel, select Roles.
      2. Open the ml_full_access role and go to the Mapped users tab.
      3. Click Manage mapping, add the mcp-client user, and click Map.

   Create an internal user and assign the ml_full_access role to them. The example below creates the mcp-client user:

   curl \
     --cacert ~/.opensearch/root.crt \
     --user admin:<password> \
     --request PUT \
     --header "Content-Type: application/json" \
     "https://<OpenSearch_host_address_with_public_access>:9200/_plugins/_security/api/internalusers/mcp-client" \
     --data '{
       "password": "<user_password>",
       "opendistro_security_roles": [
         "ml_full_access"
       ]
     }'
   

   Check that the user was created if you need to:

   curl \
     --cacert ~/.opensearch/root.crt \
     --user admin:<password> \
     --request GET \
     "https://<OpenSearch_host_address_with_public_access>:9200/_plugins/_security/api/internalusers/mcp-client"
   

   Note

   If planning to register other tools, create a role with relevant permissions. Learn more about setting up permissions from the OpenSearch guide on users and roles and the list of supported tools.

5. For steps where you edit cluster settings, create roles and users, or register tools, use the admin account or another account with enough administrative permissions. To connect the MCP client and create a Basic token, use the mcp-client user's credentials.

Start the MCP serverStart the MCP server

Run a request to the cluster API:

curl \
  --cacert ~/.opensearch/root.crt \
  --user admin:<password> \
  --request PUT \
  --header "Content-Type: application/json" \
  "https://<OpenSearch_host_address_with_public_access>:9200/_cluster/settings" \
  --data '{
    "persistent": {
      "plugins.ml_commons.mcp_server_enabled": true
    }
  }'

Register toolsRegister tools

After you start the MCP server, register the tools you want to be available to the MCP client.

See the full list of built-in tools in this OpenSearch guide.

For the registration request format, see this OpenSearch guide.

For example, you can register a basic toolkit to view indexes, schema, and search:

curl \
  --cacert ~/.opensearch/root.crt \
  --user mcp-client:<password> \
  --request POST \
  --header "Content-Type: application/json" \
  "https://<OpenSearch_host_address_with_public_access>:9200/_plugins/_ml/mcp/tools/_register" \
  --data '{
    "tools": [
      {
        "name": "ListIndexTool",
        "type": "ListIndexTool",
        "description": "Returns a list of cluster indexes",
        "attributes": {
          "input_schema": {
            "type": "object",
            "properties": {
              "indices": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "List of indexes. Specify [] for all cluster indexes"
              }
            },
            "additionalProperties": false
          }
        }
      },
      {
        "name": "IndexMappingTool",
        "type": "IndexMappingTool",
        "description": "Returns mappings and settings for the specified index",
        "attributes": {
          "input_schema": {
            "type": "object",
            "properties": {
              "index": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "List of indexes"
              }
            },
            "required": [
              "index"
            ],
            "additionalProperties": false
          }
        }
      },
      {
        "name": "SearchIndexTool",
        "type": "SearchIndexTool",
        "description": "Searches through the index using OpenSearch DSL",
        "attributes": {
          "input_schema": {
            "type": "object",
            "properties": {
              "index": {
                "type": "string"
              },
              "query": {
                "type": "string"
              }
            },
            "required": [
              "index",
              "query"
            ],
            "additionalProperties": false
          }
        }
      }
    ]
  }'

To make sure the tools were registered, run this request:

curl \
  --cacert ~/.opensearch/root.crt \
  --user mcp-client:<password> \
  --request GET \
  "https://<OpenSearch_host_address_with_public_access>:9200/_plugins/_ml/mcp/tools/_list"

If registration was successful, you will get the tools array in the response.

Generate a Basic tokenGenerate a Basic token

If the MCP client transmits Basic authentication in the header, generate a token from the username and password of the user you created:

echo -n 'mcp-client:<password>' | base64

Use the resulting value as <base64-basic-token>.

Add the MCP server to the client configurationAdd the MCP server to the client configuration

All examples below use the following URL:

https://<OpenSearch_host_address_with_public_access>:9200/_plugins/_ml/mcp

If the client does not allow you to specify a path to a CA certificate separately, install an SSL certificate to the system certificate storage in advance.

{
  "opensearch": {
    "enabled": true,
    "type": "remote",
    "url": "https://<OpenSearch_host_address_with_public_access>:9200/_plugins/_ml/mcp",
    "headers": {
      "Authorization": "Basic <base64-basic-token>"
    }
  }
}

claude mcp add --transport http opensearch \
  "https://<OpenSearch_host_address_with_public_access>:9200/_plugins/_ml/mcp" \
  --header "Authorization: Basic <base64-basic-token>"

pip3 install fastmcp

import asyncio

import httpx
from fastmcp import Client

auth = httpx.BasicAuth(
    username="mcp-client",
    password="<password>",
)


async def main():
    async with Client(
        "https://<OpenSearch_host_address_with_public_access>:9200/_plugins/_ml/mcp",
        auth=auth,
        verify="/path/to/root.crt",
    ) as client:
        for tool in await client.list_tools():
            print(tool.name)

        result = await client.call_tool("ListIndexTool", {})
        print(result)


asyncio.run(main())

Once the configuration is saved, restart the MCP client and update its settings if your application requires it.

Test the connectionTest the connection

1. Make sure the client has connected to the MCP server without authorization or TLS errors.
2. Make sure the client recognizes the registered tools, e.g., ListIndexTool, IndexMappingTool, and SearchIndexTool.
3. Run a test call of ListIndexTool and make sure you get a list of cluster indexes in the response.

For example, for FastMCP, you just need to run the script from the previous step. If the connection is configured correctly, the script will:

• Return the list of available tools.
• Call ListIndexTool.
• Return cluster indexes info.

If you are using an IDE or a local agent, open the list of MCP servers or tools in the client interface and make sure the opensearch server is active.

Delete the resources you createdDelete the resources you created

Some resources are not free of charge. Delete the resources you no longer need to avoid paying for them: