Version: 0.8.0

Register MCP tools

Introduced 0.7.0

Use this API to register one or more Model Context Protocol (MCP)-based tools with the Lucenia MCP server. Registered tools become available for use by agents through the MCP protocol.

Request

POST /_plugins/_ml/mcp/tools

Request body

The request body contains an array of tool definitions to register:

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

Tool definition fields

Field	Type	Description	Required
`name`	String	Unique name for the tool. Must be alphanumeric with underscores.	Yes
`description`	String	Human-readable description of the tool's functionality.	Yes
`parameters`	Object	Schema defining the tool's input parameters.	No
`metadata`	Object	Additional metadata about the tool.	No

Parameter schema fields

Field	Type	Description	Required
`type`	String	Parameter data type (`string`, `number`, `boolean`, `object`, `array`).	Yes
`description`	String	Description of the parameter's purpose.	Yes
`required`	Boolean	Whether the parameter is required. Default: `false`.	No
`default`	Any	Default value for optional parameters.	No
`enum`	Array	List of allowed values for the parameter.	No

Metadata fields

Field	Type	Description
`category`	String	Tool category (e.g., "search", "analysis", "utility").
`version`	String	Tool version identifier.
`author`	String	Tool author or organization.

Example requests

Register a single tool

POST /_plugins/_ml/mcp/tools
{
  "tools": [
    {
      "name": "document_search",
      "description": "Search through document collections using semantic similarity",
      "parameters": {
        "query": {
          "type": "string",
          "description": "Search query text",
          "required": true
        },
        "limit": {
          "type": "number",
          "description": "Maximum number of results to return",
          "required": false,
          "default": 10
        },
        "index": {
          "type": "string",
          "description": "Index to search in",
          "required": false,
          "default": "default"
        }
      },
      "metadata": {
        "category": "search",
        "version": "1.0.0",
        "author": "Lucenia Team"
      }
    }
  ]
}

Register multiple tools

POST /_plugins/_ml/mcp/tools
{
  "tools": [
    {
      "name": "text_analyzer",
      "description": "Analyze text sentiment and extract key topics",
      "parameters": {
        "text": {
          "type": "string",
          "description": "Text to analyze",
          "required": true
        },
        "analysis_type": {
          "type": "string",
          "description": "Type of analysis to perform",
          "required": false,
          "default": "sentiment",
          "enum": ["sentiment", "topics", "entities", "all"]
        }
      },
      "metadata": {
        "category": "analysis",
        "version": "2.1.0"
      }
    },
    {
      "name": "data_transformer",
      "description": "Transform data from one format to another",
      "parameters": {
        "input_data": {
          "type": "object",
          "description": "Data to transform",
          "required": true
        },
        "output_format": {
          "type": "string",
          "description": "Desired output format",
          "required": true,
          "enum": ["json", "xml", "csv", "yaml"]
        },
        "options": {
          "type": "object",
          "description": "Additional transformation options",
          "required": false
        }
      },
      "metadata": {
        "category": "utility",
        "version": "1.5.0"
      }
    }
  ]
}

Example response

Success response

{
  "success": true,
  "message": "Tools registered successfully",
  "data": {
    "registered_tools": [
      {
        "tool_id": "tool-abc123",
        "name": "document_search",
        "status": "active",
        "registered_at": "2024-01-01T12:00:00Z"
      }
    ],
    "total_registered": 1
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

Multiple tools response

{
  "success": true,
  "message": "Multiple tools registered successfully",
  "data": {
    "registered_tools": [
      {
        "tool_id": "tool-def456",
        "name": "text_analyzer",
        "status": "active",
        "registered_at": "2024-01-01T12:00:00Z"
      },
      {
        "tool_id": "tool-ghi789",
        "name": "data_transformer",
        "status": "active",
        "registered_at": "2024-01-01T12:00:00Z"
      }
    ],
    "total_registered": 2
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

Error responses

Invalid tool name

{
  "success": false,
  "error": {
    "type": "ValidationError",
    "message": "Invalid tool name",
    "details": {
      "field": "name",
      "reason": "Tool name must contain only alphanumeric characters and underscores"
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

Tool already exists

{
  "success": false,
  "error": {
    "type": "ConflictError",
    "message": "Tool with name 'document_search' already exists",
    "details": {
      "existing_tool_id": "tool-abc123",
      "suggestion": "Use a different name or update the existing tool"
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

Invalid parameter schema

{
  "success": false,
  "error": {
    "type": "SchemaError",
    "message": "Invalid parameter schema",
    "details": {
      "tool": "text_analyzer",
      "parameter": "analysis_type",
      "reason": "Enum values must be strings"
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

Response fields

Success response fields

Field	Type	Description
`success`	Boolean	Indicates successful registration.
`message`	String	Human-readable success message.
`data.registered_tools`	Array	List of registered tool information.
`data.total_registered`	Number	Total number of tools registered in this request.

Tool registration fields

Field	Type	Description
`tool_id`	String	Unique system-generated ID for the tool.
`name`	String	Tool name as provided in the request.
`status`	String	Tool status (`active`, `inactive`, `error`).
`registered_at`	String	ISO 8601 timestamp of registration.

Usage notes

Tool names must be unique across the entire MCP server
Tools become immediately available for use by agents after successful registration
Parameter schemas are validated according to JSON Schema specifications
Tools can be updated using the Update MCP tools API
The maximum number of tools that can be registered in a single request is 50

Request​

Request body​

Tool definition fields​

Parameter schema fields​

Metadata fields​

Example requests​

Register a single tool​

Register multiple tools​

Example response​

Success response​

Multiple tools response​

Error responses​

Invalid tool name​

Tool already exists​

Invalid parameter schema​

Response fields​

Success response fields​

Tool registration fields​

Usage notes​

Related APIs​