[Question]: Required Host Header

[etaylor77]

Initial Checks

• I searched existing issues and discussions
• I checked the README and documentation

Question Type

Configuration and authentication

Your Question

We have setup MCP as a streamable-http as required for our setup. Setting up the URL just as:

http://x.x.x.x:8000

Error: "POST / HTTP/1.1" 404 Not Found

Digging around and determined we needed to have a trailing /mcp in the URL. Now our LLM is at least attempting to connect, but appears I need some sort of header information for the connection.

Error output:

2025-12-11 00:29:08,809 - mcp.server.streamable_http_manager - DEBUG - Creating new transport
2025-12-11 00:29:08,810 - mcp.server.streamable_http_manager - INFO - Created new transport with session ID: 74acef1612a1427c81111608c03a8bef
2025-12-11 00:29:08,814 - mcp.server.transport_security - WARNING - Invalid Host header: x.x.x.x:8000

Context (Optional)

No response

Environment (Optional)

- MCP Client: Open-WebUI

[D3villl]

Have you try testing it e2e in dev env with tunneling? i recommend using cloudflare for free use once before rolling to Prod.

Below guide is safe tested in dev environment and worked for me with heavy cautions and work arounds use this as guide only / reference : Below response and troubleshooting steps are generated by Artificial Intelligence over a guidanc and enterprise grade isolation methods, followed with CARE-

please be cautious depending on your configurations before blindly following it.
This will require good engineering and testing.

Hope the below is helpful for anyone needing

🌐 MCP Server Tunnel Setup Guide

Purpose: Enable external access to your local MCP server for OpenAI Agent Builder integration.

---

📋 Prerequisites

• Python 3.10+
• MCP server with HTTP transport
• Tunnel tool: ngrok or cloudflared

---

⚙️ Configuration Requirements

1. Environment Variables (.env)

# Server must bind to all interfaces for tunnel access
FALCON_MCP_HOST=0.0.0.0

# Choose your port (default: 8000)
FALCON_MCP_PORT=8000

# Transport must support HTTP
FALCON_MCP_TRANSPORT=streamable-http

# Generate secure token: openssl rand -hex 32
MCP_ACCESS_TOKEN=your-64-character-hex-token-here

2. Server Configuration

Issue: Starlette's TrustedHostMiddleware doesn't support wildcard patterns.

Solution: Allow all hosts (safe with token authentication):

# In your server setup
from starlette.middleware.trustedhost import TrustedHostMiddleware

app.add_middleware(
    TrustedHostMiddleware,
    allowed_hosts=["*"]  # Required for tunnel access
)

---

🚀 Setup Steps

Step 1: Install Tunnel Tool

Option A - ngrok (Easiest):

# macOS
brew install ngrok

# Linux
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | \
  sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | \
  sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt update && sudo apt install ngrok

Option B - cloudflared (Better for long sessions):

# macOS
brew install cloudflare/cloudflare/cloudflared

# Linux
wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb

Step 2: Start Tunnel

Terminal 1 - Start Tunnel:

# Using ngrok
ngrok http 8000

# Using cloudflared
cloudflared tunnel --url http://localhost:8000

Copy the HTTPS URL displayed (e.g., https://abc-123.ngrok-free.app)

Step 3: Start MCP Server

Terminal 2 - Start Server:

cd your-mcp-project
python3 -m your_mcp_module.server
# OR
python3 start_server.py

Wait for: Uvicorn running on http://0.0.0.0:8000

Step 4: Test Connection

# Health check
curl -H "Authorization: Bearer YOUR-TOKEN" \
     https://YOUR-TUNNEL-URL/mcp/health

# Expected: {"status":"ok"}

# List tools
curl -X POST \
  -H "Authorization: Bearer YOUR-TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  https://YOUR-TUNNEL-URL/mcp

---

🔧 Common Issues & Fixes

❌ "502 Bad Gateway"

Cause: Server not running or port mismatch
Fix:

# Verify server is running
ps aux | grep python | grep server

# Check correct port
grep FALCON_MCP_PORT .env

# Ensure tunnel points to same port

❌ "401 Unauthorized" / "403 Forbidden"

Cause: Missing or incorrect token
Fix:

# Verify token in environment
grep MCP_ACCESS_TOKEN .env

# Ensure Authorization header format: "Bearer <token>"

❌ "Connection Refused" / Tunnel can't reach server

Cause: Server bound to 127.0.0.1 instead of 0.0.0.0
Fix:

# Check host binding
grep FALCON_MCP_HOST .env
# Must be: FALCON_MCP_HOST=0.0.0.0

# Restart server after changing

❌ "Host header validation failed"

Cause: TrustedHostMiddleware blocking tunnel domains
Fix:

# Set allowed_hosts to ["*"]
# Wildcards like "*.ngrok.io" don't work in Starlette

❌ ngrok "ERR_NGROK_3200"

Cause: Free tier limits (4hr session, 1 tunnel)
Fix: Switch to cloudflared or upgrade ngrok plan

❌ "404 Not Found" on /mcp endpoint

Cause: Wrong endpoint path or transport mode
Fix:

# For streamable-http transport, use:
# - Main endpoint: /mcp
# - Health check: /mcp/health

# Ensure FALCON_MCP_TRANSPORT=streamable-http in .env

---

AI Agent Integration

Once tunnel is verified:

1. Get Your URL:

https://your-tunnel-url.ngrok-free.app/mcp

2. Configure Agent Builder:

• MCP Server URL: https://your-tunnel-url.ngrok-free.app/mcp
• Authentication: Bearer Token
• Access Token: your-64-character-hex-token

3. Test in Agent Builder:

• Agent should list available tools
• Try a simple tool invocation

---

📊 Tunnel Comparison

Feature	ngrok (Free)	cloudflared (Free)
Session Duration	4 hours max	Unlimited
Rate Limiting	40 req/min	No limit
Concurrent Tunnels	1	Unlimited
Setup Complexity	Simple	Moderate
Best Use Case	Quick testing	Development/staging

Recommendation:

• Use ngrok for quick tests and demos
• Use cloudflared for extended development sessions

---

🔒 Security Considerations

Why allowed_hosts=["*"] is safe:

1. All requests require valid Bearer token
2. Token has 2^256 possible combinations (64 hex chars)
3. Same security model as AWS, Stripe, and other APIs
4. Tunnel URLs are randomly generated and temporary

Best Practices:

• Rotate tokens regularly
• Use different tokens for dev/staging/prod
• Monitor access logs for unusual patterns
• Restrict CORS if needed in production

---

✅ Verification Checklist

Before troubleshooting, confirm:

• .env has FALCON_MCP_HOST=0.0.0.0
• .env has FALCON_MCP_TRANSPORT=streamable-http
• Server code has allowed_hosts=["*"] in TrustedHostMiddleware
• Tunnel is running and shows active URL
• Server is running (check with ps aux | grep python)
• Ports match between tunnel and server
• Token is correctly formatted (64 hex characters)
• Health endpoint returns {"status":"ok"}

---

🛠️ Debug Commands

# Check server process
ps aux | grep python | grep server

# Check server logs
tail -f server.log

# Test local server (before tunnel)
curl http://localhost:8000/mcp/health

# Test tunnel with authentication
curl -v \
  -H "Authorization: Bearer YOUR-TOKEN" \
  https://YOUR-TUNNEL-URL/mcp/health

# Check network binding
lsof -i :8000
netstat -an | grep 8000

If issues persist after following this guide:

1. Check tunnel and server logs for error messages
2. Verify all configuration items in the checklist
3. Test local server access before adding tunnel
4. Ensure firewall/antivirus isn't blocking connections
5. Try alternative tunnel provider to isolate issue / paid subscriptions ( best recommended for local dev testing )

Common Log Patterns:

• 401 → Authentication issue
• 403 → Authorization issue (host validation)
• 404 → Wrong endpoint path
• 502/503 → Server not reachable
• 500 → Server-side error (check server logs)

[etaylor77]

I am going through your response, and first off I really appreciate you putting this together for me.

Running ngrok and cloudflare I am getting the following error just to

2025-12-12 08:06:50,040 - mcp.server.streamable_http_manager - DEBUG - Creating new transport
2025-12-12 08:06:50,040 - mcp.server.streamable_http_manager - INFO - Created new transport with session ID: ebb92b7854a4441fba279e3fcb90ee8d
2025-12-12 08:06:50,043 - mcp.server.transport_security - WARNING - Invalid Host header: x.x.x.x:8000
INFO:     x.x.x.x:59586 - "GET /mcp HTTP/1.1" 421 Misdirected Request
INFO:     x.x.x.x:49754 - "POST /mcp/health HTTP/1.1" 404 Not Found

I am still troubleshooting my setup.

[evanstoner]

FYI @etaylor77 - we (the maintainers) are not following the suggestion above from the outside contributor. It also appears AI generated to me. So I can't say whether that is relevant at all to your issue.

The output you listed originally is just a warning. Are there additional errors you're seeing?

[D3villl]

@evanstoner yes - I definitely took some help from AI - and that's a general output I got - with some heavy analysis and workaround using that as a wiki - It worked and I have also given a precautionary statement. My apologies if there was a label missed for visibility - Ai generated. Which I have corrected for anyone BLINDLY copying & Pasting.
Thanks for responding to that proactively.