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
- MCP Server: Built with
@modelcontextprotocol/sdk - SSE Transport:
SSEServerTransport for bidirectional communication - Express Server: HTTP server for web interface and SSE endpoints
- 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=: 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
- Open Claude Desktop
- Go to Settings → Integrations
- Click "Add Integration"
- Select "Model Context Protocol (MCP)"
- Configure the integration:
- Name:
Hello World MCP - URL:
https://web-production-ce65a.up.railway.app/sse - Transport:
SSE (Server-Sent Events)
- 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:
- Clone the repository:
git clone <repository-url>
cd mcphworld
- Install dependencies:
- Run locally:
🚢 Railway Deployment
This server is configured for Railway with:
railway.json: Deployment configurationProcfile: Process definition- Automatic deployment from GitHub
Deployment Steps
- Connect GitHub repository to Railway
- Railway automatically detects Node.js and deploys
- 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
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 greetgreeting (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
- Stream Consumption Issue:
- Problem:
express.json() middleware consumed request streams - Solution: Removed global JSON middleware, let SSE transport handle raw streams
- Session Management:
- Problem: Multiple SSE connections needed proper routing
- Solution: Map-based session storage with UUID keys
- 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