Skip to content

Latest commit

 

History

History
110 lines (71 loc) · 3.83 KB

sse-transport.md

File metadata and controls

110 lines (71 loc) · 3.83 KB

Server-Sent Events (SSE) Transport

This document provides detailed information about the Server-Sent Events (SSE) transport implementation for the Opik MCP server.

Overview

The SSE transport implementation allows the Opik MCP server to be hosted remotely and accessed over HTTP, enabling integration with web clients and remote systems. It uses Server-Sent Events for real-time, one-way communication from the server to clients, and standard HTTP requests for client-to-server communication.

Features

  • HTTP-based communication
  • Real-time event streaming using SSE
  • Support for multiple concurrent clients
  • Health check endpoint
  • Secure communication options
  • Configurable port and host

Configuration

The SSE transport can be configured using the following options:

Option Description Default Value
ssePort The port on which the SSE server will listen 3001
sseHost The host address to bind the SSE server localhost
sseLogPath Path to the log file for SSE transport /tmp/opik-mcp-sse.log

These options can be configured through environment variables or command-line arguments as described in the configuration documentation.

Usage

Starting the server with SSE transport

To start the MCP server with SSE transport, use the following command:

npm start -- --transport=sse

Or using the Makefile:

make start TRANSPORT=sse

Connecting to the server

Clients can connect to the SSE server using standard HTTP requests for sending commands and SSE for receiving responses.

Health Check

To verify the server is running, you can access the health check endpoint:

curl http://localhost:3001/health

A successful response will return:

{
  "status": "ok"
}

Example Client

A basic HTML client implementation is provided in the client/index.html file. This client demonstrates how to connect to the SSE server and interact with the MCP protocol.

To use the client:

  1. Start the MCP server with SSE transport
  2. Open the client/index.html file in a web browser
  3. The client will automatically connect to the SSE server and display available commands

Implementation Details

The SSE transport implementation consists of the following components:

  1. HTTP Server: An Express.js server that handles HTTP requests and serves the SSE endpoint
  2. SSE Handler: Manages SSE connections and broadcasts messages to connected clients
  3. Connection Handler: Processes incoming MCP messages and forwards them to the MCP server
  4. Message Formatting: Converts MCP messages to/from JSON format for transmission

Security Considerations

When exposing the MCP server over HTTP, consider the following security precautions:

  • Use HTTPS in production environments
  • Implement authentication for accessing the API
  • Restrict access using firewalls or API gateways
  • Do not expose sensitive data through the API

Limitations

The current SSE transport implementation has the following limitations:

  • One-way communication from server to client (SSE limitation)
  • No built-in authentication mechanism
  • Limited error handling for network-related issues

Troubleshooting

Check the SSE log file at /tmp/opik-mcp-sse.log (or your configured log path) for detailed information about connections and errors.

Common issues:

  • Port conflicts: If the port is already in use, the server will fail to start. Change the port using the ssePort configuration option.
  • Connection timeouts: Long-running SSE connections may time out in certain environments. Consider implementing reconnection logic in clients.
  • CORS issues: If accessing from a different domain, you may encounter CORS restrictions. The SSE transport includes CORS headers, but additional configuration may be needed in complex setups.