Version: 0.7.0

Remove MCP tools

Introduced 0.7.0

Use this API to remove (unregister) Model Context Protocol (MCP) tools from the Lucenia MCP server. This operation permanently removes the tool definition and makes it unavailable for future use.

warning

Removing a tool is a permanent action that cannot be undone. Ensure that no active agents or processes depend on the tool before removal.

Remove single tool

Request

DELETE /_plugins/_ml/mcp/tools/{tool_id}

Path parameters

Parameter	Type	Description	Required
`tool_id`	String	Unique tool identifier	Yes

Query parameters

Parameter	Type	Description	Default
`force`	Boolean	Force removal even if tool is currently in use	`false`
`cleanup_dependencies`	Boolean	Remove dependent resources automatically	`false`

Example requests

Remove a tool

curl -X DELETE "https://localhost:9200/_plugins/_ml/mcp/tools/tool-abc123" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"

Force remove an active tool

curl -X DELETE "https://localhost:9200/_plugins/_ml/mcp/tools/tool-def456?force=true" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"

Remove with dependency cleanup

curl -X DELETE "https://localhost:9200/_plugins/_ml/mcp/tools/tool-ghi789?cleanup_dependencies=true" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"

Example responses

Successful removal

{
  "success": true,
  "message": "Tool removed successfully",
  "data": {
    "tool_id": "tool-abc123",
    "name": "document_search",
    "status": "removed",
    "removed_at": "2024-01-01T12:30:00Z",
    "cleanup_summary": {
      "dependent_agents": 0,
      "active_sessions": 0,
      "cached_results": 15
    }
  },
  "timestamp": "2024-01-01T12:30:00Z"
}

Forced removal with warnings

{
  "success": true,
  "message": "Tool removed with active dependencies",
  "data": {
    "tool_id": "tool-def456",
    "name": "text_analyzer",
    "status": "removed",
    "removed_at": "2024-01-01T12:30:00Z",
    "cleanup_summary": {
      "dependent_agents": 3,
      "active_sessions": 1,
      "cached_results": 42
    }
  },
  "warnings": [
    {
      "type": "ActiveDependencies",
      "message": "3 agents were using this tool",
      "details": {
        "affected_agents": [
          "agent-123",
          "agent-456",
          "agent-789"
        ]
      }
    },
    {
      "type": "ActiveSession",
      "message": "1 active session was terminated",
      "details": {
        "terminated_sessions": ["session-abc123"]
      }
    }
  ],
  "timestamp": "2024-01-01T12:30:00Z"
}

Batch removal

Remove multiple tools in a single request.

Request

DELETE /_plugins/_ml/mcp/tools/_batch

Request body

{
  "tool_ids": ["string"],
  "options": {
    "force": boolean,
    "cleanup_dependencies": boolean
  }
}

Example batch request

curl -X DELETE "https://localhost:9200/_plugins/_ml/mcp/tools/_batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -d '{
    "tool_ids": [
      "tool-abc123",
      "tool-def456",
      "tool-ghi789"
    ],
    "options": {
      "force": false,
      "cleanup_dependencies": true
    }
  }'

Batch response

{
  "success": true,
  "message": "Batch removal completed",
  "data": {
    "removed_tools": [
      {
        "tool_id": "tool-abc123",
        "name": "document_search",
        "status": "removed",
        "removed_at": "2024-01-01T12:30:00Z"
      },
      {
        "tool_id": "tool-ghi789",
        "name": "data_transformer",
        "status": "removed",
        "removed_at": "2024-01-01T12:30:00Z"
      }
    ],
    "failed_removals": [
      {
        "tool_id": "tool-def456",
        "name": "text_analyzer",
        "error": "Tool is currently in use by 3 agents",
        "suggestion": "Use force=true to remove anyway"
      }
    ],
    "total_requested": 3,
    "total_removed": 2,
    "total_failed": 1
  },
  "timestamp": "2024-01-01T12:30:00Z"
}

Remove by criteria

Request

DELETE /_plugins/_ml/mcp/tools/_query

Request body

{
  "criteria": {
    "category": "string",
    "status": "string",
    "author": "string",
    "version_pattern": "string",
    "last_used_before": "string",
    "created_before": "string"
  },
  "options": {
    "force": boolean,
    "cleanup_dependencies": boolean,
    "dry_run": boolean
  }
}

Example criteria-based removal

Remove all inactive tools in the "deprecated" category:

curl -X DELETE "https://localhost:9200/_plugins/_ml/mcp/tools/_query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -d '{
    "criteria": {
      "category": "deprecated",
      "status": "inactive",
      "last_used_before": "2023-12-01T00:00:00Z"
    },
    "options": {
      "force": false,
      "cleanup_dependencies": true,
      "dry_run": false
    }
  }'

Dry run example

Preview what would be removed without actually removing:

curl -X DELETE "https://localhost:9200/_plugins/_ml/mcp/tools/_query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -d '{
    "criteria": {
      "version_pattern": "^1\\..*",
      "created_before": "2023-01-01T00:00:00Z"
    },
    "options": {
      "dry_run": true
    }
  }'

Dry run response

{
  "success": true,
  "message": "Dry run completed - no tools were actually removed",
  "data": {
    "would_remove": [
      {
        "tool_id": "tool-old123",
        "name": "legacy_processor",
        "version": "1.0.0",
        "dependencies": ["agent-old1", "agent-old2"]
      },
      {
        "tool_id": "tool-old456",
        "name": "deprecated_analyzer",
        "version": "1.2.0",
        "dependencies": []
      }
    ],
    "would_fail": [
      {
        "tool_id": "tool-old789",
        "name": "active_legacy_tool",
        "version": "1.5.0",
        "reason": "Currently in use by 5 agents"
      }
    ],
    "total_matched": 3,
    "would_remove_count": 2,
    "would_fail_count": 1
  },
  "timestamp": "2024-01-01T12:30:00Z"
}

Error responses

Tool not found

{
  "success": false,
  "error": {
    "type": "NotFoundError",
    "message": "Tool with ID 'tool-nonexistent' not found",
    "details": {
      "tool_id": "tool-nonexistent"
    }
  },
  "timestamp": "2024-01-01T12:30:00Z"
}

Tool in use (without force)

{
  "success": false,
  "error": {
    "type": "DependencyError",
    "message": "Cannot remove tool - currently in use",
    "details": {
      "tool_id": "tool-abc123",
      "active_dependencies": {
        "agents": [
          {
            "agent_id": "agent-123",
            "agent_name": "customer_service_bot",
            "last_used": "2024-01-01T12:15:00Z"
          }
        ],
        "active_sessions": [
          {
            "session_id": "session-456",
            "started_at": "2024-01-01T12:00:00Z"
          }
        ]
      },
      "suggestion": "Add force=true parameter to remove anyway"
    }
  },
  "timestamp": "2024-01-01T12:30:00Z"
}

Permission denied

{
  "success": false,
  "error": {
    "type": "PermissionError",
    "message": "Insufficient permissions to remove tool",
    "details": {
      "tool_id": "tool-abc123",
      "required_permission": "ml_commons:tool:delete",
      "user_permissions": ["ml_commons:tool:read"]
    }
  },
  "timestamp": "2024-01-01T12:30:00Z"
}

Response fields

Successful removal fields

Field	Type	Description
`tool_id`	String	Removed tool identifier
`name`	String	Tool name that was removed
`status`	String	Always "removed" for successful operations
`removed_at`	String	ISO 8601 timestamp of removal
`cleanup_summary`	Object	Summary of cleanup operations performed

Cleanup summary fields

Field	Type	Description
`dependent_agents`	Number	Number of agents that were using this tool
`active_sessions`	Number	Number of active sessions that were terminated
`cached_results`	Number	Number of cached results that were cleared

Cleanup operations

When a tool is removed, the following cleanup operations are performed:

Automatic cleanup (always performed)

Tool definition removal: The tool schema and metadata are deleted
Cache invalidation: All cached results for the tool are cleared
Index cleanup: Search indices are updated to remove tool references
Log archival: Tool usage logs are archived for audit purposes

Optional cleanup (with `cleanup_dependencies=true`)

Agent updates: Dependent agents are updated to remove tool references
Session termination: Active sessions using the tool are gracefully terminated
Notification delivery: Dependent services are notified of tool removal
Configuration updates: Related configuration files are updated

Safety measures

Pre-removal checks

Before removing a tool, the system performs the following safety checks:

Dependency verification: Identifies all agents and sessions using the tool
Permission validation: Ensures the user has sufficient permissions
Impact assessment: Evaluates the potential impact of removal
Backup creation: Creates a backup of the tool definition

Rollback capabilities

Tool definitions are backed up before removal
Rollback is possible within 24 hours of removal (if backups are enabled)
Use the Register MCP tools API to restore a tool

Best practices

Impact assessment: Always check tool dependencies before removal
Gradual deprecation: Mark tools as inactive before removing them
Communication: Notify dependent service owners before removing shared tools
Testing: Test removal in non-production environments first
Documentation: Document the reason for removal in audit logs
Backup verification: Ensure backups are created and accessible

Usage notes

Removed tools cannot be executed but may remain in audit logs
Tool IDs cannot be reused once a tool has been removed
Active tool executions are allowed to complete before removal
Batch removals are atomic - if any removal fails, none are removed (unless using force)
Removal operations are logged for audit and compliance purposes

Remove single tool​

Request​

Path parameters​

Query parameters​

Example requests​

Remove a tool​

Force remove an active tool​

Remove with dependency cleanup​

Example responses​

Successful removal​

Forced removal with warnings​

Batch removal​

Request​

Request body​

Example batch request​

Batch response​

Remove by criteria​

Request​

Request body​

Example criteria-based removal​

Dry run example​

Dry run response​

Error responses​

Tool not found​

Tool in use (without force)​

Permission denied​

Response fields​

Successful removal fields​

Cleanup summary fields​

Cleanup operations​

Automatic cleanup (always performed)​

Optional cleanup (with cleanup_dependencies=true)​

Safety measures​

Pre-removal checks​

Rollback capabilities​

Best practices​

Usage notes​

Related APIs​

Remove single tool

Request

Path parameters

Query parameters

Example requests

Remove a tool

Force remove an active tool

Remove with dependency cleanup

Example responses

Successful removal

Forced removal with warnings

Batch removal

Request

Request body

Example batch request

Batch response

Remove by criteria

Request

Request body

Example criteria-based removal

Dry run example

Dry run response

Error responses

Tool not found

Tool in use (without force)

Permission denied

Response fields

Successful removal fields

Cleanup summary fields

Cleanup operations

Automatic cleanup (always performed)

Optional cleanup (with `cleanup_dependencies=true`)

Safety measures

Pre-removal checks

Rollback capabilities

Best practices

Usage notes

Related APIs