List Connector MCP Tools API

Introduced 3.8

Use this API to list all tools available on an external MCP server through a registered MCP connector. The response includes each tool’s name, type, description, and input schema.

Flow and conversational flow agents require tools to be defined in advance during agent registration. Use this API to discover available tools and their parameters before adding MCP tools to an agent configuration. For more information, see Register Agent API.

This API differs from the List MCP Tools API, which lists tools registered on OpenSearch’s own MCP server.

Prerequisites

Before using this API, complete the following steps:

1. Enable MCP connectors by setting plugins.ml_commons.mcp_connector_enabled to true.
2. Configure trusted MCP server endpoints in plugins.ml_commons.trusted_connector_endpoints_regex.
3. Create an MCP connector with protocol mcp_sse or mcp_streamable_http.

For setup instructions, see Connecting to an external MCP server.

Endpoints

GET /_plugins/_ml/connectors/{connector_id}/tools

Path parameters

The following table lists the available path parameters.

Example request

The following example lists tools for an MCP connector with ID 1MlVyZwBBtWLSsWgaB6w:

GET /_plugins/_ml/connectors/1MlVyZwBBtWLSsWgaB6w/tools

Example response

OpenSearch connects to the external MCP server through the specified connector and returns the available tools:

{
  "tools": [
    {
      "name": "search_documents",
      "type": "McpStreamableHttpTool",
      "description": "Search a document repository for relevant content.",
      "input_schema": "{\"type\":\"object\",\"properties\":{\"query\":{\"type\":\"string\",\"description\":\"The search query.\"},\"limit\":{\"type\":\"integer\",\"description\":\"The maximum number of results to return.\",\"minimum\":1,\"maximum\":100}},\"required\":[\"query\"]}"
    },
    {
      "name": "get_weather",
      "type": "McpStreamableHttpTool",
      "description": "Retrieve current weather conditions for a specified location.",
      "input_schema": "{\"type\":\"object\",\"properties\":{\"location\":{\"type\":\"string\",\"description\":\"The city or geographic location.\"},\"units\":{\"type\":\"string\",\"description\":\"The temperature unit system.\",\"enum\":[\"celsius\",\"fahrenheit\"]}},\"required\":[\"location\"]}"
    }
  ]
}

If the MCP server exposes no tools, OpenSearch returns an empty tools array:

{
  "tools": []
}

Response body fields

The following table lists the top-level response fields.

Each object in the tools array contains the following fields.

Error responses

The following table describes common error responses.