Skip to main content
Version: 0.13.0

Remove MCP tools

Introduced 0.7.0

Removes (unregisters) Model Context Protocol (MCP) tools from the Lucenia MCP server, making them unavailable to agents.

The removal is applied on every node in the cluster, and the response reports the outcome per node.

info

Removal takes effect immediately. Confirm that no active agent depends on a tool before removing it.

Request​

POST /_plugins/_agent/mcp/tools/_remove
info

POST /_plugins/_ml/mcp/tools/_remove still works but is deprecated and emits a deprecation warning. Prefer the /_plugins/_agent path.

Request body​

The body is a JSON array of tool names — not an object. Each element may itself be a comma-separated list, and surrounding whitespace is trimmed.

POST /_plugins/_agent/mcp/tools/_remove
["WeatherTool", "StockTool"]

An empty or absent array is rejected with tools list can not be null.

Example request​

curl -X POST "https://localhost:9200/_plugins/_agent/mcp/tools/_remove" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -d '["WeatherTool", "StockTool"]'

Example response​

The response is an object keyed by node ID, with one entry per node:

{
  "bO_Y2E7tRSSVAgcqEDvJTQ": {
    "removed": true
  },
  "kY9pQ2FnQ0aVzE4xLmT1Wg": {
    "removed": true
  }
}

A node that could not remove the tool reports the reason instead, under the same key:

{
  "bO_Y2E7tRSSVAgcqEDvJTQ": {
    "removed": true
  },
  "kY9pQ2FnQ0aVzE4xLmT1Wg": {
    "not_found_exception": "tool [WeatherTool] not found"
  }
}

A per-node failure does not fail the whole request — inspect every key before treating a removal as complete.

Removing several tools​

There is no separate batch endpoint. The body is already a list, so name every tool you want removed in one request.

To remove everything, first list what is registered with the List MCP tools API and pass those names.