Hello World MCP Server

A simple Model Context Protocol (MCP) server with SSE (Server-Sent Events) transport, deployed on Railway for public access by Claude AI.

🚀 Live Demo

Server URL: https://web-production-ce65a.up.railway.app
MCP Endpoint: https://web-production-ce65a.up.railway.app/sse

🔧 Features

• SSE Transport: Server-Sent Events for real-time MCP communication
• hello tool: Simple greeting with optional name parameter
• greet tool: Custom greetings with different styles and timestamps
• Web Interface: HTML status page with connection details
• Test Endpoints: Direct HTTP endpoints for debugging

🏗️ Architecture

This server uses the MCP (Model Context Protocol) SDK with SSE transport to enable Claude AI to connect directly via a public URL without requiring local configuration.

Key Components

1. MCP Server: Built with @modelcontextprotocol/sdk
2. SSE Transport: SSEServerTransport for bidirectional communication
3. Express Server: HTTP server for web interface and SSE endpoints
4. Session Management: UUID-based session routing for multiple connections

Transport Implementation

The server implements proper MCP SSE protocol:

• GET /sse: Establishes SSE connection and provides endpoint info
• POST /sse?sessionId=<id>: Receives JSON-RPC messages from clients
• Session Routing: Maps session IDs to transport instances
• Raw Stream Handling: Avoids Express middleware that consumes request streams

📦 Installation in Claude Desktop

Adding as MCP Integration

1. Open Claude Desktop
2. Go to Settings → Integrations
3. Click "Add Integration"
4. Select "Model Context Protocol (MCP)"
5. Configure the integration:
   • Name: Hello World MCP
   • URL: https://web-production-ce65a.up.railway.app/sse
   • Transport: SSE (Server-Sent Events)
6. Save the integration

The server will automatically connect and the hello and greet tools will appear in your Claude Desktop interface.

Local Development (Optional)

If you want to run locally for development:

1. Clone the repository:

   git clone <repository-url>
   cd mcphworld
   

2. Install dependencies:

   npm install
   

3. Run locally:

   npm start
   

🚢 Railway Deployment

This server is configured for Railway with:

• railway.json: Deployment configuration
• Procfile: Process definition
• Automatic deployment from GitHub

Deployment Steps

1. Connect GitHub repository to Railway
2. Railway automatically detects Node.js and deploys
3. Public URL becomes available for MCP connections

🤖 Usage with Claude AI

Connect to the Server

Use this prompt in Claude:

I have an MCP server running at https://web-production-ce65a.up.railway.app/sse using SSE transport. Please connect to it.

Alternative: Claude Code CLI

If using Claude Code CLI:

claude mcp add --transport sse hello-world https://web-production-ce65a.up.railway.app/sse

🛠️ Available Tools

hello

• Description: Say hello to someone
• Parameters:
  • name (optional): Name of the person to greet (defaults to "World")
• Example: "Hello, Claude! 👋 This is an MCP server running on Railway!"

greet

• Description: Generate a custom greeting with timestamp
• Parameters:
  • name (required): Name of the person to greet
  • greeting (optional): Type of greeting - "formal", "casual", or "friendly" (defaults to "friendly")
• Example: "Hello Claude! Hope you're having a great day!\n\nGenerated at: 2024-01-01T12:00:00.000Z\nServer: Hello World MCP on Railway 🚂"

🧪 Testing Endpoints

For debugging and testing without MCP client:

• Status Page: https://web-production-ce65a.up.railway.app
• Hello Tool: https://web-production-ce65a.up.railway.app/test/hello?name=Test
• Greet Tool: https://web-production-ce65a.up.railway.app/test/greet?name=Test&greeting=formal
• Health Check: https://web-production-ce65a.up.railway.app/health

🛠️ Development Notes

SSE Implementation Challenges Solved

1. Stream Consumption Issue:

   • Problem: express.json() middleware consumed request streams
   • Solution: Removed global JSON middleware, let SSE transport handle raw streams

2. Session Management:

   • Problem: Multiple SSE connections needed proper routing
   • Solution: Map-based session storage with UUID keys

3. Transport Connection:

   • Problem: MCP SSE protocol requires specific endpoint format
   • Solution: Proper SSEServerTransport initialization with session routing

Key Implementation Details

// SSE endpoint establishment
app.get('/sse', (req, res) => {
  const transport = new SSEServerTransport('/sse', res);
  transports.set(transport.sessionId, transport);
  server.connect(transport);
});

// Message handling with session routing
app.post('/sse', async (req, res) => {
  const sessionId = req.query.sessionId;
  const transport = transports.get(sessionId);
  await transport.handlePostMessage(req, res);
});

📁 Project Structure

mcphworld/
├── index.js              # Main MCP server implementation
├── package.json          # Dependencies and scripts
├── railway.json          # Railway deployment config
├── Procfile              # Railway process definition
├── .gitignore            # Git ignore rules
└── README.md             # This file

🔍 Debugging

The server includes comprehensive logging:

• 🔌 SSE connection events
• 🔑 Session ID tracking
• 📨 POST message reception
• 📋 Tool list requests
• 🔧 Tool call execution

Check Railway logs for connection and usage details.

🤝 Contributing

This is a demonstration server. Feel free to fork and modify for your own MCP server implementations.

📄 License

MIT