Version: 0.7.0

Update MCP tools

Introduced 0.7.0

Use this API to update existing Model Context Protocol (MCP) tools registered with the Lucenia MCP server. You can modify tool descriptions, parameters, metadata, and status.

Request

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

Path parameters

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

Request body

{
  "name": "string",
  "description": "string",
  "parameters": {
    "parameter_name": {
      "type": "string",
      "description": "string",
      "required": boolean,
      "default": "any"
    }
  },
  "metadata": {
    "category": "string",
    "version": "string",
    "author": "string"
  },
  "status": "string"
}

Update fields

Field	Type	Description	Required
`name`	String	New tool name (must be unique)	No
`description`	String	Updated tool description	No
`parameters`	Object	Updated parameter schema	No
`metadata`	Object	Updated metadata	No
`status`	String	Tool status (`active`, `inactive`)	No

note

You only need to include the fields you want to update. Omitted fields will retain their current values.

Example requests

Update tool description

curl -X PUT "https://localhost:9200/_plugins/_ml/mcp/tools/tool-abc123" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -d '{
    "description": "Enhanced document search with semantic similarity and relevance scoring"
  }'

Update tool parameters

curl -X PUT "https://localhost:9200/_plugins/_ml/mcp/tools/tool-def456" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -d '{
    "parameters": {
      "text": {
        "type": "string",
        "description": "Text to analyze",
        "required": true
      },
      "analysis_type": {
        "type": "string",
        "description": "Type of analysis to perform",
        "required": false,
        "default": "comprehensive",
        "enum": ["sentiment", "topics", "entities", "comprehensive"]
      },
      "language": {
        "type": "string",
        "description": "Language of the text",
        "required": false,
        "default": "auto",
        "enum": ["auto", "en", "es", "fr", "de", "zh"]
      }
    }
  }'

Update metadata and version

curl -X PUT "https://localhost:9200/_plugins/_ml/mcp/tools/tool-ghi789" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -d '{
    "metadata": {
      "category": "analysis",
      "version": "2.0.0",
      "author": "ML Team",
      "tags": ["nlp", "sentiment", "classification"],
      "documentation_url": "https://docs.example.com/text-analyzer"
    }
  }'

Deactivate a tool

curl -X PUT "https://localhost:9200/_plugins/_ml/mcp/tools/tool-jkl012" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -d '{
    "status": "inactive"
  }'

Complete tool update

curl -X PUT "https://localhost:9200/_plugins/_ml/mcp/tools/tool-mno345" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -d '{
    "name": "advanced_document_processor",
    "description": "Advanced document processing with OCR, text extraction, and analysis",
    "parameters": {
      "document_url": {
        "type": "string",
        "description": "URL of the document to process",
        "required": true
      },
      "processing_options": {
        "type": "object",
        "description": "Processing configuration",
        "required": false,
        "properties": {
          "extract_text": {
            "type": "boolean",
            "default": true
          },
          "extract_images": {
            "type": "boolean",
            "default": false
          },
          "ocr_enabled": {
            "type": "boolean",
            "default": true
          }
        }
      },
      "output_format": {
        "type": "string",
        "description": "Desired output format",
        "required": false,
        "default": "json",
        "enum": ["json", "xml", "text"]
      }
    },
    "metadata": {
      "category": "document_processing",
      "version": "3.0.0",
      "author": "Document Processing Team",
      "tags": ["ocr", "text-extraction", "document-analysis"],
      "license": "MIT",
      "dependencies": ["tesseract", "opencv"]
    },
    "status": "active"
  }'

Example responses

Successful update

{
  "success": true,
  "message": "Tool updated successfully",
  "data": {
    "tool_id": "tool-abc123",
    "name": "document_search",
    "description": "Enhanced document search with semantic similarity and relevance scoring",
    "status": "active",
    "updated_fields": [
      "description"
    ],
    "updated_at": "2024-01-01T12:30:00Z",
    "version_history": {
      "current_version": 2,
      "previous_update": "2024-01-01T12:00:00Z"
    }
  },
  "timestamp": "2024-01-01T12:30:00Z"
}

Parameter schema update

{
  "success": true,
  "message": "Tool parameters updated successfully",
  "data": {
    "tool_id": "tool-def456",
    "name": "text_analyzer",
    "status": "active",
    "updated_fields": [
      "parameters"
    ],
    "parameters": {
      "text": {
        "type": "string",
        "description": "Text to analyze",
        "required": true
      },
      "analysis_type": {
        "type": "string",
        "description": "Type of analysis to perform",
        "required": false,
        "default": "comprehensive",
        "enum": ["sentiment", "topics", "entities", "comprehensive"]
      },
      "language": {
        "type": "string",
        "description": "Language of the text",
        "required": false,
        "default": "auto",
        "enum": ["auto", "en", "es", "fr", "de", "zh"]
      }
    },
    "updated_at": "2024-01-01T12:30:00Z",
    "schema_validation": {
      "status": "valid",
      "backward_compatible": true
    }
  },
  "timestamp": "2024-01-01T12:30:00Z"
}

Batch update

Request

PUT /_plugins/_ml/mcp/tools/_batch

Request body

{
  "updates": [
    {
      "tool_id": "tool-abc123",
      "updates": {
        "status": "inactive"
      }
    },
    {
      "tool_id": "tool-def456",
      "updates": {
        "metadata": {
          "version": "2.1.0"
        }
      }
    }
  ]
}

Example batch request

curl -X PUT "https://localhost:9200/_plugins/_ml/mcp/tools/_batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -d '{
    "updates": [
      {
        "tool_id": "tool-abc123",
        "updates": {
          "status": "inactive",
          "metadata": {
            "deprecation_notice": "This tool will be removed in version 1.0.0"
          }
        }
      },
      {
        "tool_id": "tool-def456",
        "updates": {
          "metadata": {
            "version": "2.2.0",
            "changelog": "Added language detection support"
          }
        }
      }
    ]
  }'

Batch response

{
  "success": true,
  "message": "Batch update completed",
  "data": {
    "updated_tools": [
      {
        "tool_id": "tool-abc123",
        "status": "updated",
        "updated_fields": ["status", "metadata"]
      },
      {
        "tool_id": "tool-def456",
        "status": "updated",
        "updated_fields": ["metadata"]
      }
    ],
    "total_requested": 2,
    "total_updated": 2,
    "failed_updates": []
  },
  "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"
}

Name conflict

{
  "success": false,
  "error": {
    "type": "ConflictError",
    "message": "Tool name 'existing_tool' is already in use",
    "details": {
      "conflicting_tool_id": "tool-xyz789",
      "suggested_names": [
        "existing_tool_v2",
        "new_existing_tool",
        "existing_tool_updated"
      ]
    }
  },
  "timestamp": "2024-01-01T12:30:00Z"
}

Invalid parameter schema

{
  "success": false,
  "error": {
    "type": "SchemaValidationError",
    "message": "Invalid parameter schema",
    "details": {
      "parameter": "analysis_type",
      "issue": "enum values must be strings",
      "provided": ["sentiment", 123, "topics"]
    }
  },
  "timestamp": "2024-01-01T12:30:00Z"
}

Backward compatibility warning

{
  "success": true,
  "message": "Tool updated with compatibility warnings",
  "data": {
    "tool_id": "tool-def456",
    "updated_fields": ["parameters"],
    "updated_at": "2024-01-01T12:30:00Z"
  },
  "warnings": [
    {
      "type": "BackwardCompatibility",
      "message": "Removed parameter 'deprecated_field' may break existing integrations",
      "details": {
        "removed_parameters": ["deprecated_field"],
        "migration_guide": "https://docs.lucenia.io/migration/tool-updates"
      }
    }
  ],
  "timestamp": "2024-01-01T12:30:00Z"
}

Best practices

Incremental updates: Update only the fields that need changes
Version tracking: Always update the version in metadata for significant changes
Backward compatibility: Consider existing integrations when changing parameters
Documentation: Update descriptions and metadata when functionality changes
Testing: Test tool updates in a non-production environment first
Change tracking: Use meaningful commit messages and changelog entries

Usage notes

Tool updates take effect immediately for new requests
Active tool executions using the old schema will continue to completion
Deactivated tools remain accessible for viewing but cannot be executed
Parameter schema changes are validated for backward compatibility
Batch updates are atomic - if any update fails, all updates are rolled back

Request​

Path parameters​

Request body​

Update fields​

Example requests​

Update tool description​

Update tool parameters​

Update metadata and version​

Deactivate a tool​

Complete tool update​

Example responses​

Successful update​

Parameter schema update​

Batch update​

Request​

Request body​

Example batch request​

Batch response​

Error responses​

Tool not found​

Name conflict​

Invalid parameter schema​

Backward compatibility warning​

Best practices​

Usage notes​

Related APIs​

Request

Path parameters

Request body

Update fields

Example requests

Update tool description

Update tool parameters

Update metadata and version

Deactivate a tool

Complete tool update

Example responses

Successful update

Parameter schema update

Batch update

Request

Request body

Example batch request

Batch response

Error responses

Tool not found

Name conflict

Invalid parameter schema

Backward compatibility warning

Best practices

Usage notes

Related APIs