Streamable HTTP MCP Server with Azure OpenAI GPT-4o
This project implements a Streamable HTTP MCP (Model Context Protocol) Server using FastAPI and integrates it with Azure OpenAI GPT-4o for intelligent tool usage.
🚀 Features
- MCP Server: Streamable HTTP server with SSE support
- Azure OpenAI Integration: GPT-4o with tool calling capabilities
- Simple Tools: Calculator, Weather (mock), and Time tools
- Docker Setup: Easy deployment with docker-compose
- Real-time Communication: Server-Sent Events (SSE) for streaming responses
📋 Prerequisites
- Docker and Docker Compose
- Azure OpenAI account with GPT-4o deployment
- Python 3.11+ (for local development)
🛠️ Quick Setup
- Clone and setup:
# Copy environment file
cp .env.example .env
# Edit .env with your Azure OpenAI credentials
nano .env
- Configure Azure OpenAI:
AZURE_OPENAI_API_KEY=your_api_key_here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o
AZURE_OPENAI_API_VERSION=2024-02-01
- Start the MCP server:
- Run the GPT-4o client:
📖 Usage Examples
The client automatically demonstrates various tool interactions:
Query: What's the current time?
Response: The current time is 2024-01-15T14:30:45.123456
Query: Calculate 15 * 42 + 33
Response: The result is 663
Query: What's the weather like in New York?
Response: The weather in New York is currently sunny with a temperature of 22°C...
Query: Can you get the weather for London and then calculate the percentage if the temperature was 20 degrees and now it's 25 degrees?
Response: The weather in London is currently 22°C and sunny...
The percentage increase from 20°C to 25°C is 25%.
- Calculator: Evaluate mathematical expressions
- Weather: Get mock weather data for any location
- Time: Get current timestamp
🏗️ Architecture
[GPT-4o Client] <--HTTP--> [MCP Server] <--SSE--> [Tools]
| |
| [Calculator]
| [Weather]
| [Time]
🌐 API Endpoints
POST /sse - Main MCP communication endpointGET /health - Health checkGET /tools - List available tools
📝 Manual Testing
Test the MCP server directly:
# Health check
curl http://localhost:8000/health
# List tools
curl http://localhost:8000/tools
# Test SSE endpoint
curl -X POST http://localhost:8000/sse \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": "1", "method": "tools/list", "params": {}}'
🐳 Docker Commands
# Start MCP server only
docker-compose up -d mcp-server
# Run client once
docker-compose run --rm client
# View logs
docker-compose logs -f mcp-server
# Stop everything
docker-compose down
🧪 Development
Local Development
# Install dependencies
pip install -r requirements.txt
# Run server locally
python mcp_server.py
# Run client locally (in another terminal)
source .env
python client.py
- Create a new tool class in
mcp_server.py - Add tool definition to
TOOLS dictionary - Add handler in
MCPHandler.handle_tools_call
Example:
class NewTool:
@staticmethod
def do_something(param: str) -> Dict[str, Any]:
return {"result": f"Processed: {param}"}
# Add to TOOLS dictionary
TOOLS["new_tool"] = {
"name": "new_tool",
"description": "Does something useful",
"inputSchema": {
"type": "object",
"properties": {
"param": {"type": "string", "description": "Input parameter"}
},
"required": ["param"]
}
}
🐛 Troubleshooting
Common Issues
- Connection refused: Make sure MCP server is running on port 8000
- Authentication errors: Check your Azure OpenAI credentials in
.env - Tool call failures: Check MCP server logs for detailed error messages
Debug Mode
Enable debug logging:
docker-compose logs -f mcp-server
🔒 Security Notes
- Never commit your
.env file with real credentials - Use environment variables in production
- Consider adding authentication for production deployments
📄 License
MIT License - feel free to use and modify as needed.