Magnazee/railwaymcp

MCP Server with HTTP Streaming - Railway Deployment

This project demonstrates deploying a Model Context Protocol (MCP) server with HTTP streaming support to Railway. The server uses the modern Streamable HTTP transport which provides efficient bidirectional communication over a single HTTP endpoint.

Features

• ✅ Streamable HTTP Transport: Modern MCP transport with full bidirectional streaming
• ✅ HTTP Streaming: Supports real-time communication and server-sent events
• ✅ Multiple Tools: Weather API, BMI calculator, and more
• ✅ Resources & Prompts: Dynamic greetings and question generation
• ✅ Railway Optimized: Configured for seamless Railway deployment

Tools Available

1. get_weather(city) - Get simulated weather data for any city
2. calculate_bmi(weight_kg, height_m) - Calculate BMI with category classification
3. greeting://{{name}} - Personalized greeting resource
4. ask_question(topic, style) - Generate styled questions about topics

Local Development

Prerequisites

• Python 3.8+
• pip or uv package manager

Setup

# Clone this repository
git clone <your-repo-url>
cd mcp-railway-server

# Install dependencies
pip install -r requirements.txt
# OR with uv
uv pip install -r requirements.txt

# Run locally
python main.py

The server will start on http://localhost:8000/mcp with Streamable HTTP transport.

Testing the Server

You can test the server using the MCP Inspector or any MCP client that supports Streamable HTTP:

# Install MCP CLI tools (if available)
uv tool install mcp

# Test with MCP Inspector
mcp inspect http://localhost:8000/mcp

Railway Deployment

Method 1: Deploy from GitHub (Recommended)

1. Fork this repository to your GitHub account

2. Create a new Railway project:

   • Go to Railway
   • Click "New Project"
   • Select "Deploy from GitHub repo"
   • Choose your forked repository

3. Configure deployment:

   • Railway will automatically detect the railway.json configuration
   • The app will build using Nixpacks
   • No additional environment variables needed

4. Generate domain:

   • Go to your service settings
   • Navigate to "Networking" tab
   • Click "Generate Domain"
   • Your MCP server will be available at: https://your-app-name.railway.app/mcp

Method 2: Deploy with Railway CLI

# Install Railway CLI
npm install -g @railway/cli

# Login to Railway
railway login

# Initialize project
railway init

# Deploy
railway up

Method 3: Deploy with Docker

If you prefer using Docker:

# Build Docker image
docker build -t mcp-server .

# Run locally (test)
docker run -p 8000:8000 -e PORT=8000 mcp-server

# Deploy to Railway (Railway will handle this automatically if Dockerfile is present)

Configuration

Environment Variables

Railway automatically sets the PORT environment variable. No additional configuration is required for basic deployment.

Optional environment variables you can add:

• MCP_SERVER_NAME: Custom server name (default: "Railway MCP Server")
• DEBUG: Set to "true" for debug logging

MCP Client Configuration

To connect an MCP client to your deployed server, use this configuration:

{
  "mcpServers": {
    "railway-mcp": {
      "type": "streamable-http",
      "url": "https://your-app-name.railway.app/mcp"
    }
  }
}

Architecture

This server uses:

• FastMCP: High-level MCP server framework
• Streamable HTTP Transport: Modern bidirectional communication protocol
• Railway Platform: Serverless deployment with automatic scaling

Key Benefits of Streamable HTTP:

• Single endpoint for all communication (/mcp)
• Automatic connection upgrades to SSE when needed
• Better performance than traditional HTTP+SSE approach
• Full bidirectional communication support

Troubleshooting

Common Issues

1. Port binding error locally:

   # Make sure port 8000 is available
   lsof -i :8000
   

2. Railway deployment fails:

   • Check that requirements.txt includes mcp>=1.8.0
   • Ensure railway.json has correct start command
   • Verify Railway has access to your GitHub repository

3. MCP client connection issues:

   • Ensure client supports Streamable HTTP transport
   • Use correct URL format: https://your-app.railway.app/mcp
   • Check that Railway domain is generated and accessible

Logs and Debugging

View Railway logs:

railway logs

Enable debug mode by setting environment variable:

railway variables set DEBUG=true

Next Steps

1. Add Authentication: Implement OAuth 2.1 for secured endpoints
2. Add Real APIs: Replace simulated data with real weather/data APIs
3. Database Integration: Add persistent storage with Railway PostgreSQL
4. Monitoring: Set up logging and monitoring for production use

Resources

• MCP Specification
• MCP Python SDK
• Railway Documentation
• Streamable HTTP Transport Spec

License

MIT License - see LICENSE file for details.