Version: 0.7.0

List MCP tools

Introduced 0.7.0

Use this API to retrieve information about registered Model Context Protocol (MCP) tools on the Lucenia MCP server. This endpoint provides details about available tools, their parameters, and current status.

Request

GET /_plugins/_ml/mcp/tools

Query parameters

Parameter	Type	Description	Default
`size`	Integer	Number of tools to return (1-100)	`10`
`from`	Integer	Starting offset for pagination	`0`
`sort`	String	Sort field (`name`, `created_at`, `category`)	`name`
`order`	String	Sort order (`asc`, `desc`)	`asc`
`category`	String	Filter by tool category	None
`status`	String	Filter by tool status (`active`, `inactive`)	None
`search`	String	Search in tool names and descriptions	None

Example requests

List all tools

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

List tools with pagination

curl -X GET "https://localhost:9200/_plugins/_ml/mcp/tools?size=20&from=10" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"

Filter tools by category

curl -X GET "https://localhost:9200/_plugins/_ml/mcp/tools?category=search&size=50" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"

Search tools

curl -X GET "https://localhost:9200/_plugins/_ml/mcp/tools?search=document%20analysis" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"

Sort by creation date

curl -X GET "https://localhost:9200/_plugins/_ml/mcp/tools?sort=created_at&order=desc" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"

Example response

Success response

{
  "success": true,
  "message": "Tools retrieved successfully",
  "data": {
    "tools": [
      {
        "tool_id": "tool-abc123",
        "name": "document_search",
        "description": "Search through document collections using semantic similarity",
        "status": "active",
        "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"
        },
        "created_at": "2024-01-01T12:00:00Z",
        "updated_at": "2024-01-01T12:00:00Z",
        "usage_stats": {
          "total_calls": 1234,
          "success_rate": 0.98,
          "avg_execution_time_ms": 245
        }
      },
      {
        "tool_id": "tool-def456",
        "name": "text_analyzer",
        "description": "Analyze text sentiment and extract key topics",
        "status": "active",
        "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",
          "author": "ML Team"
        },
        "created_at": "2024-01-02T08:30:00Z",
        "updated_at": "2024-01-05T14:20:00Z",
        "usage_stats": {
          "total_calls": 856,
          "success_rate": 0.95,
          "avg_execution_time_ms": 180
        }
      }
    ],
    "pagination": {
      "total": 25,
      "size": 10,
      "from": 0,
      "has_more": true
    },
    "filters_applied": {
      "category": null,
      "status": null,
      "search": null
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

Empty result response

{
  "success": true,
  "message": "No tools found matching the criteria",
  "data": {
    "tools": [],
    "pagination": {
      "total": 0,
      "size": 10,
      "from": 0,
      "has_more": false
    },
    "filters_applied": {
      "category": "nonexistent",
      "status": null,
      "search": null
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

Response fields

Tool object fields

Field	Type	Description
`tool_id`	String	Unique system-generated identifier
`name`	String	Tool name
`description`	String	Tool description
`status`	String	Current status (`active`, `inactive`, `error`)
`parameters`	Object	Tool parameter schema
`metadata`	Object	Additional tool metadata
`created_at`	String	ISO 8601 creation timestamp
`updated_at`	String	ISO 8601 last update timestamp
`usage_stats`	Object	Tool usage statistics

Parameter schema fields

Field	Type	Description
`type`	String	Parameter data type
`description`	String	Parameter description
`required`	Boolean	Whether parameter is required
`default`	Any	Default value for optional parameters
`enum`	Array	Allowed values (if applicable)

Metadata fields

Field	Type	Description
`category`	String	Tool category
`version`	String	Tool version
`author`	String	Tool author

Usage statistics fields

Field	Type	Description
`total_calls`	Number	Total number of tool invocations
`success_rate`	Number	Success rate (0.0 to 1.0)
`avg_execution_time_ms`	Number	Average execution time in milliseconds

Pagination fields

Field	Type	Description
`total`	Number	Total number of tools matching criteria
`size`	Number	Number of tools in current response
`from`	Number	Starting offset
`has_more`	Boolean	Whether more results are available

Get single tool

Request

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

Path parameters

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

Example request

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

Example response

{
  "success": true,
  "message": "Tool retrieved successfully",
  "data": {
    "tool_id": "tool-abc123",
    "name": "document_search",
    "description": "Search through document collections using semantic similarity",
    "status": "active",
    "parameters": {
      "query": {
        "type": "string",
        "description": "Search query text",
        "required": true
      },
      "limit": {
        "type": "number",
        "description": "Maximum number of results to return",
        "required": false,
        "default": 10
      }
    },
    "metadata": {
      "category": "search",
      "version": "1.0.0",
      "author": "Lucenia Team"
    },
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z",
    "usage_stats": {
      "total_calls": 1234,
      "success_rate": 0.98,
      "avg_execution_time_ms": 245,
      "recent_calls": [
        {
          "timestamp": "2024-01-01T11:45:00Z",
          "execution_time_ms": 230,
          "success": true
        },
        {
          "timestamp": "2024-01-01T11:30:00Z",
          "execution_time_ms": 260,
          "success": true
        }
      ]
    }
  },
  "timestamp": "2024-01-01T12:00: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:00:00Z"
}

Invalid parameters

{
  "success": false,
  "error": {
    "type": "ValidationError",
    "message": "Invalid query parameters",
    "details": {
      "field": "size",
      "reason": "Size must be between 1 and 100"
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

Advanced filtering

Complex search query

curl -X GET "https://localhost:9200/_plugins/_ml/mcp/tools?search=neural%20OR%20sentiment&category=analysis&status=active&sort=usage_stats.total_calls&order=desc" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"

Usage statistics filtering

Get most frequently used tools:

curl -X GET "https://localhost:9200/_plugins/_ml/mcp/tools?sort=usage_stats.total_calls&order=desc&size=5" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"

Get tools with high success rates:

curl -X GET "https://localhost:9200/_plugins/_ml/mcp/tools?min_success_rate=0.95" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"

Usage notes

Tool listings include usage statistics for monitoring and optimization
Pagination is recommended for large tool collections
Search functionality supports partial matches in names and descriptions
Category filtering helps organize tools by functionality
Status filtering allows focusing on active/inactive tools only

Request​

Query parameters​

Example requests​

List all tools​

List tools with pagination​

Filter tools by category​

Search tools​

Sort by creation date​

Example response​

Success response​

Empty result response​

Response fields​

Tool object fields​

Parameter schema fields​

Metadata fields​

Usage statistics fields​

Pagination fields​

Get single tool​

Request​

Path parameters​

Example request​

Example response​

Error responses​

Tool not found​

Invalid parameters​

Advanced filtering​

Complex search query​

Usage statistics filtering​

Usage notes​

Related APIs​

Request

Query parameters

Example requests

List all tools

List tools with pagination

Filter tools by category

Search tools

Sort by creation date

Example response

Success response

Empty result response

Response fields

Tool object fields

Parameter schema fields

Metadata fields

Usage statistics fields

Pagination fields

Get single tool

Request

Path parameters

Example request

Example response

Error responses

Tool not found

Invalid parameters

Advanced filtering

Complex search query

Usage statistics filtering

Usage notes

Related APIs