MCP SSE message

Introduced 0.7.0

This endpoint handles standard message interactions for the Model Context Protocol (MCP). It enables communication with the MCP server in Lucenia through Server-Sent Events (SSE). The SSE Message API provides direct, low-level access to tools using the JSON-RPC (remote procedure call) protocol structure.

Overview

The MCP SSE Message API differs from the agent framework approach, where tools are configured using parameters during agent registration. Instead, it provides direct access to MCP tools through standard JSON-RPC message patterns, allowing for more flexible and dynamic tool interactions.

Send message

Request

POST /_plugins/_ml/mcp/sse/message

Request body

{
  "session_id": "string",
  "message": {
    "jsonrpc": "2.0",
    "id": "string|number",
    "method": "string",
    "params": {}
  }
}

Request fields

Field	Type	Description	Required
session_id	String	Active SSE session identifier	Yes
message.jsonrpc	String	JSON-RPC version (must be "2.0")	Yes
message.id	String/Number	Unique identifier for the request	Yes
message.method	String	Method to invoke on the MCP server	Yes
message.params	Object	Parameters for the method call	No

Supported methods

Tool discovery methods

tools/list

List all available tools on the MCP server.

{
  "session_id": "session-123",
  "message": {
    "jsonrpc": "2.0",
    "id": "req-001",
    "method": "tools/list",
    "params": {}
  }
}

tools/get

Get detailed information about a specific tool.

{
  "session_id": "session-123",
  "message": {
    "jsonrpc": "2.0",
    "id": "req-002",
    "method": "tools/get",
    "params": {
      "name": "document_search"
    }
  }
}

Tool execution methods

tools/call

Execute a specific tool with provided parameters.

{
  "session_id": "session-123",
  "message": {
    "jsonrpc": "2.0",
    "id": "req-003",
    "method": "tools/call",
    "params": {
      "name": "document_search",
      "arguments": {
        "query": "machine learning algorithms",
        "limit": 5,
        "index": "research_papers"
      }
    }
  }
}

Server information methods

server/info

Get information about the MCP server.

{
  "session_id": "session-123",
  "message": {
    "jsonrpc": "2.0",
    "id": "req-004",
    "method": "server/info",
    "params": {}
  }
}

server/ping

Ping the server to check connectivity.

{
  "session_id": "session-123",
  "message": {
    "jsonrpc": "2.0",
    "id": "req-005",
    "method": "server/ping",
    "params": {}
  }
}

Example requests

List available tools

curl -X POST "https://localhost:9200/_plugins/_ml/mcp/sse/message" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -d '{
    "session_id": "session-abc123",
    "message": {
      "jsonrpc": "2.0",
      "id": "list-tools-001",
      "method": "tools/list",
      "params": {}
    }
  }'

Execute a search tool

curl -X POST "https://localhost:9200/_plugins/_ml/mcp/sse/message" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -d '{
    "session_id": "session-abc123",
    "message": {
      "jsonrpc": "2.0",
      "id": "search-001",
      "method": "tools/call",
      "params": {
        "name": "document_search",
        "arguments": {
          "query": "neural networks deep learning",
          "limit": 10,
          "include_metadata": true
        }
      }
    }
  }'

Get tool information

curl -X POST "https://localhost:9200/_plugins/_ml/mcp/sse/message" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -d '{
    "session_id": "session-abc123",
    "message": {
      "jsonrpc": "2.0",
      "id": "tool-info-001",
      "method": "tools/get",
      "params": {
        "name": "text_analyzer"
      }
    }
  }'

Example responses

Successful response

The response is sent through the established SSE connection as an event:

event: message_response
data: {"jsonrpc": "2.0", "id": "search-001", "result": {"matches": [{"title": "Deep Learning Fundamentals", "score": 0.98, "metadata": {"author": "Smith, J.", "year": 2023}}], "total": 1, "execution_time_ms": 145}}
id: response-001

Tool list response

event: message_response
data: {"jsonrpc": "2.0", "id": "list-tools-001", "result": {"tools": [{"name": "document_search", "description": "Search through document collections", "parameters": {"query": {"type": "string", "required": true}, "limit": {"type": "number", "default": 10}}}, {"name": "text_analyzer", "description": "Analyze text sentiment and topics", "parameters": {"text": {"type": "string", "required": true}, "analysis_type": {"type": "string", "enum": ["sentiment", "topics"]}}}], "total": 2}}
id: response-002

Error response

event: message_response
data: {"jsonrpc": "2.0", "id": "search-001", "error": {"code": -32602, "message": "Invalid params", "data": {"field": "limit", "reason": "Must be a positive integer"}}}
id: response-003

Server info response

event: message_response
data: {"jsonrpc": "2.0", "id": "req-004", "result": {"server": {"name": "Lucenia MCP Server", "version": "0.7.0"}, "capabilities": ["tools", "streaming"], "protocol_version": "2024-11-05"}}
id: response-004

JSON-RPC error codes

The MCP server uses standard JSON-RPC 2.0 error codes:

Code	Message	Description
-32700	Parse error	Invalid JSON in request
-32600	Invalid Request	Request is not a valid JSON-RPC object
-32601	Method not found	Requested method does not exist
-32602	Invalid params	Invalid method parameters
-32603	Internal error	Server internal error
-32000 to -32099	Server error	Server-defined errors

Custom error codes

Code	Message	Description
-32000	Session not found	Invalid or expired session ID
-32001	Tool not found	Requested tool does not exist
-32002	Tool execution failed	Tool execution encountered an error
-32003	Rate limit exceeded	Too many requests from client
-32004	Authentication required	Session requires authentication

Response handling

Success responses

All successful responses follow the JSON-RPC 2.0 format and are delivered through the SSE connection:

{
  "jsonrpc": "2.0",
  "id": "original-request-id",
  "result": {
    // Method-specific result data
  }
}

Error responses

Error responses also follow JSON-RPC 2.0 format:

{
  "jsonrpc": "2.0",
  "id": "original-request-id",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      // Additional error details
    }
  }
}

Advanced usage patterns

Batch requests

Send multiple requests in a single batch:

{
  "session_id": "session-123",
  "message": [
    {
      "jsonrpc": "2.0",
      "id": "req-001",
      "method": "tools/get",
      "params": {"name": "document_search"}
    },
    {
      "jsonrpc": "2.0",
      "id": "req-002",
      "method": "tools/get",
      "params": {"name": "text_analyzer"}
    }
  ]
}

Asynchronous tool execution

For long-running tools, use asynchronous execution:

{
  "session_id": "session-123",
  "message": {
    "jsonrpc": "2.0",
    "id": "async-001",
    "method": "tools/call",
    "params": {
      "name": "large_dataset_analyzer",
      "arguments": {
        "dataset_id": "dataset-123",
        "analysis_depth": "comprehensive"
      },
      "options": {
        "async": true,
        "callback_id": "analysis-callback-001"
      }
    }
  }
}

Client implementation example

JavaScript client

class MCPClient {
  constructor(baseUrl, credentials) {
    this.baseUrl = baseUrl;
    this.credentials = credentials;
    this.sessionId = null;
    this.requestId = 0;
    this.pendingRequests = new Map();
  }

  async sendMessage(method, params = {}) {
    const id = `req-${++this.requestId}`;
    const message = {
      session_id: this.sessionId,
      message: {
        jsonrpc: "2.0",
        id: id,
        method: method,
        params: params
      }
    };

    const response = await fetch(`${this.baseUrl}/_plugins/_ml/mcp/sse/message`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Basic ${this.credentials}`
      },
      body: JSON.stringify(message)
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return new Promise((resolve, reject) => {
      this.pendingRequests.set(id, { resolve, reject });
      // Response will be received through SSE connection
    });
  }

  async listTools() {
    return await this.sendMessage('tools/list');
  }

  async callTool(name, arguments) {
    return await this.sendMessage('tools/call', { name, arguments });
  }

  handleSSEMessage(eventData) {
    const response = JSON.parse(eventData);
    const pending = this.pendingRequests.get(response.id);
    
    if (pending) {
      this.pendingRequests.delete(response.id);
      if (response.error) {
        pending.reject(new Error(response.error.message));
      } else {
        pending.resolve(response.result);
      }
    }
  }
}

Best practices

1. Request IDs: Use unique, descriptive request IDs for easier debugging
2. Error handling: Implement comprehensive error handling for all JSON-RPC error codes
3. Session management: Monitor session health and handle reconnections
4. Rate limiting: Implement client-side rate limiting to avoid server limits
5. Timeout handling: Set appropriate timeouts for tool execution requests
6. Batch operations: Use batch requests for multiple related operations

Related APIs

• MCP SSE session
• Register MCP tools
• List MCP tools