initial commit for MCP server in OpenSearch

[zane-neo]

Description

This PR is to support MCP server within OpenSearch, the feature is experimental and you'll need to enable transport-reactor-netty4 to test, for more details can refer this: https://docs.opensearch.org/docs/latest/install-and-configure/configuring-opensearch/network-settings/#selecting-the-transport

There are several experimental APIs are introduced:

POST /_plugins/_ml/mcp_tools/_register
POST /_plugins/_ml/mcp_tools/_remove
GET /_plugins/_ml/sse
POST /_plugins/_ml/sse/message

The later twos are standard MCP's sse and message APIs. An example of using these API is like below:

1. Create tools for MCP server:

POST /_plugins/_ml/mcp_tools/_register
{
    "tools": [
        {
            "name": "PPLTool",
            "description": "Use this tool to transfer natural language to generate PPL and execute PPL to query inside. Use this tool after you know the index name, otherwise, call IndexRoutingTool first. The input parameters are: {index:IndexName, question:UserQuestion}",
            "params": {
                "model_type": "FINETUNE",
                "model_id": "${your_model_id}"
            },
            "schema": {
                "type": "object",
                "properties": {
                    "parameters": {
                        "type": "object",
                        "question": {
                            "type": "string"
                        },
                        "index": {
                            "type": "string"
                        }
                    }
                },
                "required": [
                    "question",
                    "index"
                ]
            }
        },
        {
            "name": "ListIndexTool",
            "description": "This is my first list index tool",
            "params": {},
            "schema": {
                "type": "object",
                "properties": {
                    "indices": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "OpenSearch index name list, separated by comma. for example: [\"index1\", \"index2\"], use empty array [] to list all indices in the cluster"
                    }
                },
                "additionalProperties": false
            }
        }
    ]
}

Sample response:

{
    "_ZNV5BrNTVm6ilcM7Jn1pw": {
        "created": true
    },
    "NZ9aiUCrSp2b5KBqdJGJKw": {
        "created": true
    }
}

2. Get a connection session for current client:

GET /_plugins/_ml/sse

Sample response:

event: endpoint
data: /sse/message?sessionId=9d6aeca5-89f6-4df3-82fc-625098362198

3. List tools in MCP server:

POST /_plugins/_ml/sse/message?sessionId=9d6aeca5-89f6-4df3-82fc-625098362198
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list"
}

Sample response:

event: message
data: {"jsonrpc":"2.0","id":"100","result":{"tools":[{"name":"ListIndexTool","description":"This is my first list index tool","inputSchema":{"type":"object","properties":{"indices":{"description":"OpenSearch index name list, separated by comma. for example: [\"index1\", \"index2\"], use empty array [] to list all indices in the cluster","type":"array","items":{"type":"string"}}},"additionalProperties":false}}]}}

4. Execute tool in MCP server:

POST /_plugins/_ml/sse/message?sessionId=9d6aeca5-89f6-4df3-82fc-62509836219
{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/call",
    "params": {
        "name": "ListIndexTool",
        "arguments": {
            "input": {
                "index": ["test"]
            }
        }
    }
}

Sample response:

event: message
data: {"jsonrpc":"2.0","id":"110","result":{"content":[{"type":"text","text":"row,health,status,index,uuid,pri(number of primary shards),rep(number of replica shards),docs.count(number of available documents),docs.deleted(number of deleted documents),store.size(store size of primary and replica shards),pri.store.size(store size of primary shards)\n1,green,open,.plugins-ml-config,2E1HgTkGS1-jwEYlyfd0og,1,0,1,0,4kb,4kb\n2,green,open,top_queries-2025.04.25-51488,I6BkcS5kSrOfh7Lgi4IcDg,1,0,28,12,138.9kb,138.9kb\n3,green,open,.opendistro_security,VSZdbnKYRKmvnmihS5TJ9Q,1,0,9,0,77.8kb,77.8kb\n"}],"isError":false}}

5. Remove tools in MCP server:

POST /_plugins/_ml/mcp_tools/_remove
[
    "ListIndexTool", "PPLTool"
]

Sample response:

{
    "_ZNV5BrNTVm6ilcM7Jn1pw": {
        "removed": true
    },
    "NZ9aiUCrSp2b5KBqdJGJKw": {
        "removed": true
    }
}

A example project that uses MCP client to connect to MCP server in OpenSearch can be found here: https://github.com/zane-neo/opensearch-mcpserver-test-example

Related Issues

opensearch-project/OpenSearch#17577

Check List

• New functionality includes testing.
• New functionality has been documented.
• API changes companion pull request created.
• Commits are signed per the DCO using --signoff.
• Public documentation issue/PR created.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[opensearch-trigger-bot]

The backport to 3.0 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-3.0 3.0
# Navigate to the new working tree
cd .worktrees/backport-3.0
# Create a new branch
git switch --create backport/backport-3781-to-3.0
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 9b0294d905ad2fb7f1526194241f3591c8a057a3
# Push it to GitHub
git push --set-upstream origin backport/backport-3781-to-3.0
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-3.0

Then, create a pull request where the base branch is 3.0 and the compare/head branch is backport/backport-3781-to-3.0.

[mingshl]

If this is targeting 3.0 please add backport 3.0 label @zane-neo

[jngz-es]

One more high level question.
Did you try do a load test on the execute tool api? I strongly suggest you to do a little bit.
As I mentioned above, your server logic is in rest handler RestMcpConnectionMessageStreamingAction, not through transport call. If my understanding is correct, mcp tools call would use netty thread which would block other incoming rest requests. Usually rest handler should be light-weight, I recommend to use another thread pool as what I did for model inference streaming, https://github.com/jngz-es/ml-commons/blob/7b7e0b16ceeeafe67eb42e752ca5b37a78e3bf90/ml-algorithms/src/main/java/org/opensearch/ml/engine/algorithms/remote/HttpJsonConnectorExecutor.java#L191.

[ylwu-amzn]

Add cluster setting to enable/disable this feature

[zane-neo]

One more high level question. Did you try do a load test on the execute tool api? I strongly suggest you to do a little bit. As I mentioned above, your server logic is in rest handler RestMcpConnectionMessageStreamingAction, not through transport call. If my understanding is correct, mcp tools call would use netty thread which would block other incoming rest requests. Usually rest handler should be light-weight, I recommend to use another thread pool as what I did for model inference streaming, https://github.com/jngz-es/ml-commons/blob/7b7e0b16ceeeafe67eb42e752ca5b37a78e3bf90/ml-algorithms/src/main/java/org/opensearch/ml/engine/algorithms/remote/HttpJsonConnectorExecutor.java#L191.

@jngz-es, if there are any blocking operations either in rest handler or in transport handler, it'll block the transport_worker threads which are the NIO threads of netty which indeed can cause serious problems, but if you check the code here: https://github.com/opensearch-project/ml-commons/pull/3781/files#diff-5efd0e0dcc84b1e4e115cbb4f4dda4c812bfd5e1ae8317056a99c7fa3b92e861R127-R135 which is where the tools executed, they're been executed in a non-blocking fashion(using action listener), so it seems fine in the performance perspective. Anyway I'll do a performance test for this once I complete the following bug fixes, thanks!

[ylwu-amzn]

Use _plugins/_ml/mcp as URL prefix for all MCP related APIs

[zane-neo]

Few High Level Questions about this:

1. Do we need experimental streaming feature in core for this to work (I could not make it work by cloning)
2. I think the server Endpoint should be /_plugins/_ml/mcp because only /sse seems generic.
3. Generally when we initialize an MCP client using MCP SDK, we need to provide the URL.
   The SDK internally does these things:

• GET {url}/sse to get the sessionID and the message endpoint like: /messages/?session_id=c381902fafd3436295cd07df156498d2
• Next, the client performs the POST call to initialize the connection: {url}/messages/?session_id=c381902fafd3436295cd07df156498d2
• 3rd initialization step and tool calls follow.

But in the code I see that we have these URLs:

• GET /_plugins/_ml/sse
• POST /_plugins/_ml/sse/message?sessionId=9d6aeca5-89f6-4df3-82fc-625098362198

Perhaps we do not need /sse in messages endpoint.

I took a look on java client and python client and there are discrepancy between them:
java client connect: https://github.com/modelcontextprotocol/java-sdk/blob/0.9.x/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java#L343
java client message: https://github.com/modelcontextprotocol/java-sdk/blob/0.9.x/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java#L415

So in java client you specifies a baseUri, e.g. http://localhost:8000 and it will be concatenated with default /sse or the message endpoint returned /see/message?sessionId=xxx.

python client connect: https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/sse.py#L47
python client message: https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/sse.py#L64

So in python client the url is a SSE url, e.g. http://localhost:8000/sse, and the message endpoint will be the concatenated with the message uri returned by server, e.g. /message?sessionId=xxx

So the common pattern is: /sse for sse endpoint and /sse/message for message endpoint. I'll add an extra parameter in the /sse endpoint to let user control which type of uri should return, also we should bring this up in MCP community to let them know the issue.