Register MCP tools
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/_agent/mcp/tools/_register
note
Agent, tool, and MCP APIs now use the preferred _plugins/_agent namespace. The legacy _plugins/_ml/... route still works for backward compatibility but is deprecated and will be removed in a future release.
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/_agent/mcp/tools/_register
{
"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/_agent/mcp/tools/_register
{
"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