mcp-sse-example

A reference implementation for integrating Model Context Protocol (MCP) capabilities into web applications using Server-Sent Events (SSE) as the transport layer.

This project demonstrates how to create an MCP server that communicates with clients using the SSE transport protocol. It enables web applications to access powerful MCP capabilities while maintaining a persistent connection for real-time communication with AI models.

Key features:

• Implement MCP servers using Server-Sent Events for web compatibility
• Create custom MCP tools that can be accessed from web clients
• Connect any MCP-compatible client to your SSE-based server
• Extend AI assistants with web-based capabilities through standardized protocols

The Model Context Protocol (MCP) supports multiple transport mechanisms, with SSE being ideal for web applications:

• Server-Sent Events (SSE): A web standard for establishing a unidirectional connection where servers can push updates to clients
• MCP over SSE: Implements the MCP protocol using SSE as the transport layer, enabling web clients to interact with MCP servers
• Real-time AI interactions: Allows continuous streaming of AI responses while maintaining tool execution capabilities

• Node.js (v18 or higher)
• NPM or Yarn
• A Brave Search API key for the example search tool

# Clone the repository
git clone https://github.com/yourusername/mcp-sse-example.git
cd mcp-sse-example

# Install backend dependencies
cd backend
npm install

Create a .env file in the backend directory with your API credentials:

BRAVE_API_KEY=your_api_key_here

# Build and start the server
npm run build
npm run start

The MCP SSE server will be available at http://localhost:3001.

# From the project root
docker-compose up -d

This implementation uses:

1. Express.js as the web server
2. SSEServerTransport from the MCP SDK to handle the SSE protocol
3. McpServer to register and manage tools

The server exposes two main endpoints:

• /sse - For establishing SSE connections
• /messages - For receiving messages from clients

The core server implementation:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import express from "express";

const server = new McpServer({
  name: "Example SSE Server",
  version: "1.0.0",
});

// Register tools
server.tool("example_tool", { param: z.string() }, async ({ param }) => ({
  content: [{ type: "text", text: `Processed: ${param}` }],
}));

const app = express();
let transport: SSEServerTransport;

app.get("/sse", async (req, res) => {
  transport = new SSEServerTransport("/messages", res);
  await server.connect(transport);
});

app.post("/messages", async (req, res) => {
  await transport.handlePostMessage(req, res);
});

app.listen(3001);

Many MCP clients support the SSE transport protocol, including:

• Claude Desktop App
• Continue
• Cursor
• LibreChat
• And many others listed at modelcontextprotocol.io/clients

When debugging your MCP SSE implementation:

# Follow logs in real-time (for MacOS)
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

For more detailed debugging instructions, see the MCP debugging guide.

Contributions are welcome! Please feel free to submit a Pull Request.

This project is licensed under the MIT License - see the LICENSE file for details.

• Model Context Protocol - Official MCP documentation
• MCP TypeScript SDK - Official TypeScript implementation
• MCP Inspector - Interactive tool for testing MCP servers