# HTTP Transport Upgrade Summary
## ✅ What Was Added
Your pfSense MCP Server has been successfully upgraded from **v4.0.0 to v4.1.0** with full **Streamable HTTP transport** support!
### Changes Made
#### 1. **Core Server Updates** (`src/main.py`)
- ✅ Added support for Streamable HTTP transport alongside stdio
- ✅ Stateless HTTP mode for scalability (`stateless_http=True, json_response=True`)
- ✅ Auto-detection of transport mode via `MCP_MODE` environment variable
- ✅ Configurable host/port for HTTP mode
#### 2. **Configuration Files**
- ✅ Updated `.env.example` with HTTP transport options
- ✅ Created `mcp-http.json` - HTTP configuration for Claude
- ✅ Created `HTTP_TRANSPORT.md` - Complete HTTP setup guide
#### 3. **Helper Scripts**
- ✅ Created `run-http.sh` - Quick start script for HTTP mode
- ✅ Created `test-http-transport.py` - Validation script
#### 4. **Documentation**
- ✅ Created `PYTHON_VERSION_REQUIREMENT.md` - Python 3.10+ setup guide
- ✅ Created this upgrade summary
## 🚀 How to Use
### Quick Start (After Installing Python 3.10+)
**1. Install Python 3.10+ (Required)**
```bash
brew install python@3.12
```
**2. Set up environment**
```bash
# Copy and configure your environment
cp .env.example .env
nano .env # Edit with your pfSense details
# Set transport mode
# For HTTP: MCP_MODE=http
# For stdio: MCP_MODE=stdio
```
**3. Install dependencies**
```bash
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
**4. Start the server**
**HTTP Mode:**
```bash
export MCP_MODE=http
./run-http.sh
# Server starts at: http://localhost:8000/mcp
```
**stdio Mode:**
```bash
export MCP_MODE=stdio
python3.12 -m src.main
```
### Configure Claude
**For HTTP Transport (works with CLI and Web):**
Add to `~/.claude/settings.json`:
```json
{
"mcpServers": {
"pfsense": {
"url": "http://localhost:8000/mcp"
}
}
}
```
**For stdio Transport (CLI only):**
Add to `~/.claude/settings.json`:
```json
{
"mcpServers": {
"pfsense": {
"command": "python3.12",
"args": ["-m", "src.main"],
"cwd": "/Users/mmaxwell/pfsense-mcp-server",
"env": {
"PFSENSE_URL": "https://your-pfsense.local",
"PFSENSE_API_KEY": "your-api-key",
"MCP_MODE": "stdio"
}
}
}
}
```
## 🆚 Transport Comparison
| Feature | stdio | HTTP |
|---------|-------|------|
| **Claude CLI** | ✅ Yes | ✅ Yes |
| **Claude Web** | ❌ No | ✅ Yes |
| **Remote Access** | ❌ Local only | ✅ Yes |
| **Scalability** | Single instance | Horizontal scaling |
| **Setup** | Simpler | Requires hosting |
| **Security** | File-based | Network-based |
## 📋 Environment Variables
### HTTP Transport Settings
```bash
MCP_MODE=http # Transport mode (http or stdio)
MCP_HOST=0.0.0.0 # Bind address for HTTP
MCP_PORT=8000 # HTTP port
```
### pfSense Configuration
```bash
PFSENSE_URL=https://your-pfsense.local
PFSENSE_API_KEY=your-api-key-here
PFSENSE_VERSION=CE_2_8_0 # or PLUS_24_11
AUTH_METHOD=api_key
VERIFY_SSL=true
```
## 🔧 Testing
```bash
# Test configuration (requires Python 3.10+)
python3.12 test-http-transport.py
# Manual test - HTTP mode
curl -X POST http://localhost:8000/mcp \\
-H "Content-Type: application/json" \\
-d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
```
## 📚 Documentation Files
- **HTTP_TRANSPORT.md** - Complete HTTP setup guide
- **PYTHON_VERSION_REQUIREMENT.md** - Python 3.10+ installation
- **mcp-http.json** - HTTP configuration template
- **.env.example** - Updated with HTTP options
- **run-http.sh** - HTTP startup script
- **test-http-transport.py** - Validation script
## 🎯 Next Steps
1. **Install Python 3.10+** - See `PYTHON_VERSION_REQUIREMENT.md`
2. **Configure .env** - Copy from `.env.example` and add your pfSense details
3. **Choose transport mode** - Set `MCP_MODE=http` or `MCP_MODE=stdio`
4. **Test** - Run `test-http-transport.py` to validate setup
5. **Start server** - Use `./run-http.sh` or `python3.12 -m src.main`
6. **Configure Claude** - Add server to Claude settings
## 🐛 Troubleshooting
### Python Version Error
```
ERROR: No matching distribution found for fastmcp>=0.4.0
```
**Solution**: Install Python 3.10+ (see PYTHON_VERSION_REQUIREMENT.md)
### Port Already in Use
```bash
lsof -i :8000 # Check what's using the port
export MCP_PORT=8001 # Use a different port
```
### Connection Refused
- Check firewall settings
- Verify MCP_HOST and MCP_PORT settings
- Ensure server is running: `curl http://localhost:8000/mcp`
## 💡 Tips
- **Development**: Use `stdio` mode (simpler, no network)
- **Production**: Use `http` mode with HTTPS reverse proxy
- **Both**: Run two instances on different ports!
- **Docker**: See docker-compose.yml for containerized deployment
## 🔒 Security Notes
- Use HTTPS in production (add nginx/caddy reverse proxy)
- Store API keys securely in .env (never commit!)
- Enable rate limiting: `ENABLE_RATE_LIMITING=true`
- Use firewall rules to restrict access
- Consider VPN for remote access
## 📈 What's New in v4.1.0
- ✨ **Streamable HTTP transport** support
- ✨ **Stateless operation** for horizontal scaling
- ✨ **Dual transport mode** - switch between stdio and HTTP
- ✨ **Auto-detection** of transport from environment
- ✨ **Production-ready** with proper configuration
- 📝 **Comprehensive documentation** for HTTP setup
## 🆘 Support
- 📖 Read `HTTP_TRANSPORT.md` for detailed setup
- 🐍 Check `PYTHON_VERSION_REQUIREMENT.md` for Python setup
- 🔧 Run `test-http-transport.py` to diagnose issues
- 💬 Ask questions in GitHub Issues
---
**Server Version**: 4.1.0
**Transport Modes**: stdio, http
**Status**: ✅ Ready for testing (requires Python 3.10+)
