mcp-sse-demo

IAMDS-GMBH/mcp-sse-demo

3.2

If you are the rightful owner of mcp-sse-demo and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This document provides a comprehensive overview of a Model Context Protocol (MCP) server utilizing Server-Sent Events (SSE) for real-time communication.

Tools
3
Resources
0
Prompts
0

MCP SSE Protocol Demo

An educational demonstration of the Server-Sent Events (SSE) protocol used by Model Context Protocol (MCP) servers.

🎯 Overview

This project demonstrates how MCP servers use Server-Sent Events (SSE) for real-time, bidirectional communication between clients and servers. It includes a fully functional MCP server, interactive web UI, and comprehensive logging to help you understand the SSE protocol.

📚 What is SSE?

Server-Sent Events (SSE) is a web standard that enables servers to push real-time updates to clients over HTTP. Unlike WebSockets which are bidirectional, SSE is:

  • Unidirectional: Server → Client only (for events)
  • HTTP-based: Works over standard HTTP/1.1 or HTTP/2
  • Text-based: Uses simple text format for messages
  • Auto-reconnecting: Browser automatically handles reconnection

🔄 How MCP Uses SSE

MCP achieves bidirectional communication by combining:

  1. SSE for Server → Client: The server pushes JSON-RPC responses and notifications via SSE
  2. HTTP POST for Client → Server: The client sends JSON-RPC requests via regular HTTP POST

This approach provides:

  • Real-time server-to-client messaging
  • Compatibility with standard HTTP infrastructure
  • Automatic reconnection handling
  • Simple implementation using native browser APIs

🚀 Getting Started

Prerequisites

  • Node.js 18+
  • npm or yarn

Installation

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Start the server
npm start

The server will start at http://localhost:3000

Development

# Build and run in one command
npm run dev

🎮 Using the Demo

  1. Open the Web UI: Navigate to http://localhost:3000 in your browser

  2. Watch the Connection: The connection status indicator shows when the SSE connection is established

  3. Try the Tools: Use the tool cards to invoke MCP tools:

    • Echo Tool: Echoes back your message
    • Calculator Tool: Performs simple calculations
    • Timestamp Tool: Returns current server time

  4. Observe the Flow: Watch the event log and message inspector to see:

    • SSE connection establishment
    • Client requests (HTTP POST)
    • Server responses (SSE events)
    • JSON-RPC message format

📂 Project Structure

sse-demo/
├── src/
│   └── server.ts          # MCP server with SSE transport
├── public/
│   ├── index.html         # Web UI
│   ├── styles.css         # Styling
│   └── client.js          # SSE client implementation
├── package.json
├── tsconfig.json
└── README.md

🔍 Key Concepts Demonstrated

SSE Connection Flow

  1. Client initiates: GET /sse - Opens persistent connection
  2. Server responds: Sets headers (Content-Type: text/event-stream)
  3. Connection persists: Server keeps connection alive
  4. Events flow: Server sends events as they occur

Message Format

SSE messages follow this format:

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"Hello"}]}}

Bidirectional Communication

Client → Server:  POST /message (JSON-RPC request)
Server → Client:  SSE event (JSON-RPC response)

🛠️ MCP Tools

The demo includes three sample tools:

Echo Tool

  • Purpose: Demonstrates basic request/response flow
  • Input: Message string
  • Output: Echoed message

Calculate Tool

  • Purpose: Shows parameter handling
  • Input: Two numbers and an operation (add, subtract, multiply, divide)
  • Output: Calculation result

Timestamp Tool

  • Purpose: Demonstrates server-initiated data
  • Input: None
  • Output: Current server timestamp

📊 Server Endpoints

  • GET / - Web UI
  • GET /sse - SSE connection endpoint
  • POST /message - Client message endpoint
  • GET /status - Server status and active connections

🧪 Testing the Protocol

Using Browser DevTools

  1. Open DevTools (F12)
  2. Go to Network tab
  3. Filter by "EventSource" or "sse"
  4. Watch the SSE connection and events in real-time

Using curl

# Connect to SSE endpoint
curl -N http://localhost:3000/sse

# Send a message (in another terminal)
curl -X POST http://localhost:3000/message \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"echo","arguments":{"message":"Hello"}}}'

📝 Server Logging

The server provides detailed console logging showing:

  • Connection establishment
  • SSE transport setup
  • Incoming requests
  • Tool invocations
  • Message routing
  • Connection lifecycle

Look for these log prefixes:

  • 🔌 [SSE] - SSE connection events
  • 📨 [POST] - HTTP POST requests
  • 🔧 [MCP] - MCP protocol events
  • 📋 [MCP] - Tool list requests

🔧 Configuration

Server Port

Change the port in src/server.ts:

const port = 3000; // Change to your preferred port

SSE Endpoint

Modify the endpoint path in src/server.ts:

const transport = new SSEServerTransport('/message', res);

And update public/client.js accordingly:

const response = await fetch('/message', { ... });

📖 Learn More

🤝 Contributing

This is an educational demo. Feel free to:

  • Add more example tools
  • Enhance the UI
  • Improve documentation
  • Add more protocol explanations

📄 License

MIT License - Feel free to use this code for learning and education.

🙏 Acknowledgments

Built with:

Happy learning! 🚀

For questions or issues, please refer to the MCP documentation.