Skip to main content
Version: 0.7.0

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. These APIs allow you to register tools, establish streaming connections, and communicate with the MCP server through Server-Sent Events (SSE).

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, ensure that:

  1. The default HTTP transport method does not support streaming. You must install the transport-reactor-netty4 HTTP transport plugin and use it as the default HTTP transport layer: 
    # Install the transport plugin
    ./bin/lucenia-plugin install transport-reactor-netty4

    # Configure as default transport in lucenia.yml
    http.type: reactor-netty4
  2. You have appropriate permissions to manage ML Commons resources

API overview​

The MCP server APIs provide the following functionality:

Tool management APIs​

Streaming communication APIs​

Base endpoint​

All MCP server APIs are accessed through the following base endpoint:

/_plugins/_ml/mcp/

Authentication and security​

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

# Example with basic authentication
curl -X GET "https://localhost:9200/_plugins/_ml/mcp/tools" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Content-Type: application/json"

Common parameters​

Standard request headers​

  • Content-Type: application/json for most requests
  • Accept: text/event-stream for SSE endpoints
  • Authorization: Authentication credentials

Common response fields​

All MCP API responses include standard fields:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // API-specific response data
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

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
  • 409 Conflict: Resource already exists
  • 500 Internal Server Error: Server error

Error response format​

{
  "success": false,
  "error": {
    "type": "ValidationError",
    "message": "Invalid tool configuration",
    "details": {
      "field": "tool_name",
      "reason": "Tool name cannot be empty"
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

Rate limiting​

MCP server APIs are subject to rate limiting to ensure system stability:

  • Default limit: 100 requests per minute per client
  • Burst limit: 10 requests per second
  • Rate limit headers: Responses include rate limit information
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

Usage patterns​

1. Tool discovery and registration​

# Register tools with the MCP server
POST /_plugins/_ml/mcp/tools
{
  "tools": [
    {
      "name": "search_documents",
      "description": "Search through document collection",
      "parameters": {
        "query": {
          "type": "string",
          "description": "Search query"
        }
      }
    }
  ]
}

2. Streaming communication​

# Establish SSE session
GET /_plugins/_ml/mcp/sse
Accept: text/event-stream

# Send messages through the session
POST /_plugins/_ml/mcp/sse/message
{
  "session_id": "session-123",
  "message": {
    "type": "tool_call",
    "tool": "search_documents",
    "parameters": {
      "query": "machine learning"
    }
  }
}

Monitoring and debugging​

Server status​

Check the MCP server status:

GET /_plugins/_ml/mcp/status

Active sessions​

List active SSE sessions:

GET /_plugins/_ml/mcp/sessions

Logs​

Monitor MCP server logs for debugging:

tail -f logs/lucenia.log | grep "MCP"

Best practices​

  1. Connection management: Properly close SSE connections when no longer needed
  2. Error handling: Implement robust error handling for network issues
  3. Tool naming: Use descriptive, unique names for MCP tools
  4. Security: Always use HTTPS in production environments
  5. Rate limiting: Implement client-side rate limiting to avoid hitting server limits

Validation rules​

Tool name validation​

  • Must be unique across all tools
  • Can contain alphanumeric characters and underscores only
  • Must be between 3 and 50 characters
  • Cannot start with a number

Parameter schema validation​

  • Must follow JSON Schema Draft 7 specification
  • Required parameters cannot have default values
  • Enum values must match the parameter type
  • Nested objects must have proper schema definitions

Version management​

  • Version strings should follow semantic versioning (semver)
  • Major version changes require explicit confirmation
  • Breaking changes should be documented in metadata

Next steps​