MCP Simple Server

A simple MCP server with streamable HTTP transport that supports basic math tools like add and multiply.

A minimal, reference implementation of a Model Context Protocol server with streamable HTTP transport. Built with FastMCP following the official Anthropic MCP specification 2025-06-18. Perfect starting point for building remote MCP servers.

This project serves as a simple, well-documented reference for developers who want to:

- Build their first MCP server
- Deploy MCP servers to cloud platforms (Railway, Heroku, Render)
- Understand the MCP protocol implementation
- Create a foundation for more sophisticated MCP solutions

- ✅Two Math Tools:addandmultiplyfunctions
- ✅Streamable HTTP Transport: Modern MCP protocol with SSE support
- ✅Session Management: Proper MCP initialization flow
- ✅Remote Deployment: Railway, Heroku, Render deployment configs
- ✅Automated Testing: Complete protocol validation and debugging tools
- ✅Claude Desktop Integration: Ready for AI assistant integration
- ✅Reference Implementation: Well-documented code for learning

git clone https://github.com/oleksandrsirenko/mcp-simple-server.git cd mcp-simple-server uv sync source .venv/bin/activate python main.py

Server starts at:http://localhost:8000/mcp/

🧪 Starting MCP Server Tests ✅ Initialize successful - Server: Simple Server ✅ Initialized notification sent ✅ Found 2 tools: add, multiply ✅ Add tool returned correct result ✅ Multiply tool returned correct result 🎉 All tests passed!

{"name": "add", "arguments": {"a": 25, "b": 17}} → Returns: 42

{"name": "multiply", "arguments": {"a": 8, "b": 6}} → Returns: 48

For testing your local development server running onlocalhost:8000:

curl -X POST http://localhost:8000/mcp/ \ -H "Content-Type: application/json" \ -H "MCP-Protocol-Version: 2025-06-18" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"clientInfo":{"name":"test-client","version":"1.0.0"}}}'

curl -X POST http://localhost:8000/mcp/ \ -H "Content-Type: application/json" \ -H "MCP-Protocol-Version: 2025-06-18" \ -H "Accept: application/json, text/event-stream" \ -H "Mcp-Session-Id: YOUR_SESSION_ID" \ -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl -X POST http://localhost:8000/mcp/ \ -H "Content-Type: application/json" \ -H "MCP-Protocol-Version: 2025-06-18" \ -H "Accept: application/json, text/event-stream" \ -H "Mcp-Session-Id: YOUR_SESSION_ID" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

curl -X POST http://localhost:8000/mcp/ \ -H "Content-Type: application/json" \ -H "MCP-Protocol-Version: 2025-06-18" \ -H "Accept: application/json, text/event-stream" \ -H "Mcp-Session-Id: YOUR_SESSION_ID" \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add","arguments":{"a":25,"b":17}}}'

For testing your deployed server, replacelocalhost:8000with your deployment URL:

# Example with Railway deployment curl -X POST https://your-app.railway.app/mcp/ \ -H "Content-Type: application/json" \ -H "MCP-Protocol-Version: 2025-06-18" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"clientInfo":{"name":"test-client","version":"1.0.0"}}}'

Note: For comprehensive remote testing, use the automated test script:

python test_deployment.py your-app.railway.app

git add . git commit -m "ready for deployment" git push origin main

- Go torailway.app
- Click "Deploy from GitHub repo"
- Select your repository
- Railway auto-detects Dockerfile and deploys

python test_deployment.py your-app-name.up.railway.app

heroku create your-mcp-server git push heroku main

docker build -t mcp-simple-server . docker run -p 8000:8000 mcp-simple-server

{ "mcpServers": { "simple-server": { "command": "python", "args": ["main.py"], "cwd": "/path/to/mcp-simple-server" } } }

Remote Server Configuration (Recommended)

For remote servers deployed to Railway, Heroku, or Render, use themcp-remotepackage:

{ "mcpServers": { "simple-server-remote": { "command": "npx", "args": [ "-y", "mcp-remote", "https://your-app.railway.app/mcp/", "--allow-http", "--header", "Accept: application/json, text/event-stream" ] } } }

- Usenpxwith the-yflag to auto-installmcp-remote
- Include the trailing slash in the URL:/mcp/
- Add the--allow-httpflag for HTTP connections
- Include the Accept header for proper SSE support

Alternative: Direct Python Proxy (Advanced)

For advanced users or debugging purposes, you can create a custom Python proxy:

{ "mcpServers": { "simple-server-proxy": { "command": "python", "args": ["claude_mcp_proxy.py"], "cwd": "/path/to/mcp-simple-server" } } }

Note: This requires theclaude_mcp_proxy.pyscript from the repository and is mainly for debugging purposes. Usemcp-remotefor production.

- macOS:~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:%APPDATA%\Claude\claude_desktop_config.json

- "Can you add 42 and 18 for me?"
- "What's 7 times 9?"
- "What tools do you have available?"

Claude will use your MCP server to perform calculations! 🎉

@mcp.tool() def subtract(a: float, b: float) -> float: """Subtract two numbers""" return a - b @mcp.tool() def divide(a: float, b: float) -> float: """Divide two numbers""" if b == 0: raise ValueError("Cannot divide by zero") return a / b

- HOST: Server host (default: 127.0.0.1, use 0.0.0.0 for deployment)
- PORT: Server port (default: 8000, Railway sets this automatically)

Note: For Railway deployment, FastMCP will automatically bind to0.0.0.0:$PORT.

mcp-simple-server/ ├── main.py # MCP server (~25 lines) ├── test_server.py # Local server tests (~300 lines) ├── test_deployment.py # Remote deployment tests ├── test_host_binding.py # Host binding tests ├── test_proxy_script.py # Proxy testing script ├── test_streamable_app.py # Streamable HTTP tests ├── test_tool_verification.py # Tool verification tests ├── debug_railway_server.py # Railway debugging utilities ├── debug_fastmcp.py # FastMCP debugging utilities ├── claude_mcp_proxy.py # Claude Desktop proxy (optional) ├── start.sh # Shell startup script ├── pyproject.toml # Project configuration ├── README.md # This documentation ├── uv.lock # Dependency lock file ├── .gitignore # Git ignore patterns ├── .python-version # Python version specification ├── Dockerfile # Docker deployment ├── railway.toml # Railway configuration ├── Procfile # Heroku configuration └── render.yaml # Render configuration

- FastMCP: High-level MCP implementation from Anthropic
- Streamable HTTP: Modern transport with SSE streaming support
- Session Management: Stateful connections with session IDs
- JSON-RPC 2.0: Standard protocol for message exchange
- Protocol 2025-06-18: Latest MCP specification
- Port 8000: Default FastMCP server port (configurable via PORT env var)

- Framework: FastMCP (official Anthropic library)
- Transport: Streamable HTTP with Server-Sent Events
- Protocol: MCP 2025-06-18 specification
- Dependencies:httpx>=0.28.1,mcp>=1.9.4
- Client sendsinitializerequest
- Server responds with capabilities and session ID
- Client sendsinitializednotification
- Normal operations begin (tools/list, tools/call, etc.)

Tools return simple Python values (float, int, str) which FastMCP automatically wraps in the proper MCP response format.

# Check if port is in use lsof -i :8000 # Try different port PORT=3000 python main.py

# Run automated test python test_server.py # Check server logs for detailed errors

- Verify JSON configuration syntax- Use a JSON validator
- Check server URL accessibility- Test withcurlor browser
- Restart Claude Desktopafter config changes
- Ensure proper MCP endpoint path- Use/mcp/with trailing slash
- Usemcp-remotefor remote servers- Don't usecurlfor remote connections

Test your deployed server with the provided script:

# Test your deployed server (replace with your URL) python test_deployment.py your-app.railway.app # Or with full URL python test_deployment.py https://your-app.railway.app

This will run the complete MCP protocol test suite against your remote server.

- Wrong endpoint: Use/mcp/(with trailing slash)
- Missing headers: Include all required MCP headers
- Session management: Must sendinitializednotification afterinitialize
- Remote connections: Usemcp-remote, notcurlfor Claude Desktop
- Port binding: Use0.0.0.0:$PORTfor deployment, not127.0.0.1

dependencies = [ "httpx>=0.28.1", # HTTP client for testing "mcp>=1.9.4", # Official Anthropic MCP library ]

- mcp: Official Anthropic MCP Python SDK
- httpx: Modern HTTP client for automated testing
- Python: Requires Python >=3.10
- Fork the repository
- Make your changes
- Run tests:python test_server.py
- Test deployment:python test_deployment.py your-test-url
- Ensure all tests pass
- Submit a pull request

- MCP Specification 2025-06-18
- FastMCP Documentation
- Claude Desktop
- Railway Deployment
- Render Deployment
- mcp-remote Package

An MCP server for ABP.IO that enables AI models to interact with your ABP applications and framework.