Skip to main content
Version: 0.7.1

MCP server APIs

Introduced 0.7.0

The Model Context Protocol (MCP) server APIs provide endpoints for managing and interacting with MCP tools in Lucenia. The MCP server in ML Commons uses the Streamable HTTP transport protocol to communicate with clients.

important

This is an experimental feature and is not recommended for use in a production environment. For updates on its progress, see the Lucenia version history.

Prerequisites​

Before using MCP server APIs, enable the MCP server functionality in your cluster:

PUT /_cluster/settings
{
  "persistent": {
    "plugins.ml_commons.mcp_server_enabled": "true"
  }
}

API overview​

The MCP server APIs provide the following functionality:

MCP server endpoint​

Tool management APIs​

Base endpoint​

The MCP server is exposed through the following endpoint:

/_plugins/_ml/mcp

This endpoint implements the Streamable HTTP transport defined by the Model Context Protocol (MCP). It allows agents or clients to connect to Lucenia and discover or invoke available tools.

Authentication and security​

MCP server APIs require authentication. Include appropriate authentication headers based on your Lucenia security configuration:

# Example with basic authentication
curl -X POST "https://localhost:9200/_plugins/_ml/mcp" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Error handling​

MCP server APIs return standard HTTP status codes and error responses:

Success responses​

  • 200 OK: Successful operation
  • 201 Created: Resource created successfully
  • 204 No Content: Successful operation with no response body

Error responses​

  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 405 Method Not Allowed: Invalid HTTP method (e.g., GET request to the MCP endpoint)
  • 409 Conflict: Resource already exists
  • 500 Internal Server Error: Server error

Next steps​