Skip to main content

HTTP MCP Servers

Monitor and manage remote HTTP-based MCP servers through a transparent proxy.

Overview​

HTTP MCP Servers support enables monitoring of remote/cloud-hosted MCP servers that use HTTP/SSE (Server-Sent Events) transport. MCP Gatekeeper provides full visibility into HTTP MCP traffic through a transparent proxy architecture.

Architecture​

Agent (Windsurf/Claude/Amazon Q)
  ↓ connects to proxy
HTTP Proxy (127.0.0.1:8000/proxy/{agent_type}/{name})
  ↓ logs & forwards
Actual HTTP MCP Server (e.g., https://api.githubcopilot.com/mcp/)
  ↓ response
HTTP Proxy (logs response)
  ↓
Agent receives response

Adding HTTP Servers​

From the Web UI​

  1. Navigate to HTTP Servers page
  2. Click "Add HTTP Server"
  3. Configure server:
    • Name: Unique identifier (e.g., github)
    • Server URL: Actual HTTP MCP server URL
    • Headers: Optional HTTP headers (e.g., Authorization)
    • Timeout: Request timeout in seconds (default: 30)
    • Retries: Number of retry attempts (default: 3)
  4. Click Save

Configuration Example​

{
  "name": "github",
  "server_url": "https://api.githubcopilot.com/mcp/",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  },
  "timeout": 30,
  "retries": 3
}

How It Works​

Transparent Proxy​

MCP Gatekeeper runs a transparent HTTP proxy that:

  1. Receives agent connections on 127.0.0.1:8000/proxy/{agent_type}/{server_name}
  2. Forwards requests to the actual HTTP MCP server
  3. Logs all request/response traffic
  4. Tracks metrics (latency, errors, request counts)
  5. Returns responses to the agent

Agent Configuration​

When you add an HTTP server to an agent, the configuration is automatically rewritten:

Amazon Q Config:

{
  "mcpServers": {
    "github": {
      "url": "http://127.0.0.1:8000/proxy/amazon_q/github"
    }
  }
}

Windsurf Config (uses serverUrl):

{
  "mcpServers": {
    "github": {
      "serverUrl": "http://127.0.0.1:8000/proxy/windsurf/github"
    }
  }
}

Gemini CLI Config (uses httpUrl):

{
  "mcpServers": {
    "github": {
      "httpUrl": "http://127.0.0.1:8000/proxy/gemini_cli/github"
    }
  }
}

The agent type is included in the proxy URL path for tracking. The original server URL and headers are stored securely in the database and used by the proxy.

Managing HTTP Servers​

Viewing Servers​

The HTTP Servers page shows:

  • Server Name: Unique identifier
  • Status: Active/Inactive
  • Server URL: Actual target URL
  • Proxy URL: Local proxy URL for agents
  • Last Activity: When last used
  • Actions: Test, Edit, Delete

Testing Connection​

  1. Navigate to HTTP Servers page
  2. Find the server
  3. Click Test button
  4. View connection status and latency

Editing Servers​

  1. Click Edit on a server
  2. Update configuration
  3. Click Save

Note: Updating headers or URL affects all agents using this server.

Deleting Servers​

  1. Click Delete on a server
  2. Confirm deletion

Warning: This will break any agent configurations using this server.

Adding to Agents​

From Agents Page​

  1. Navigate to Agents page
  2. Select an agent
  3. Click Add Server
  4. Select an HTTP server from the list (marked with HTTP badge)
  5. Click Add Server

The proxy URL and environment variables are automatically configured.

Security​

Headers Storage​

  • Headers are stored in the database
  • Sensitive values can be masked in UI
  • Headers are only visible to the proxy service

SSL/TLS Support​

For HTTPS servers with custom certificates:

# Set custom CA certificate
export SSL_CERT_PATH=/path/to/ca-cert.pem

Local-Only Proxy​

The proxy runs on 127.0.0.1 (localhost only) for security:

  • Not accessible from network
  • Only local agents can connect
  • No external exposure

Monitoring​

Metrics Tracked​

  • Request Count: Total requests proxied
  • Response Count: Total responses received
  • Latency: Average response time
  • Error Rate: Percentage of failed requests
  • 24-hour Activity: Request timeline

View Metrics​

  1. Navigate to HTTP Servers page
  2. Click on a server
  3. View metrics dashboard

Real-time Monitoring​

HTTP server activity appears in:

  • Servers page (combined with STDIO)
  • Metrics page (unified dashboard)
  • Logs page (request/response logs)

Troubleshooting​

Connection Fails​

Problem: Cannot connect to HTTP server

Solutions:

  1. Test connection using Test button
  2. Verify server URL is correct
  3. Check network connectivity
  4. Verify headers (especially Authorization)
  5. Check server is accessible

SSL Certificate Errors​

Problem: SSL verification fails

Solutions:

  1. Set SSL_CERT_PATH environment variable
  2. Add custom CA certificate
  3. Verify server certificate is valid

Agent Not Connecting​

Problem: Agent cannot connect to proxy

Solutions:

  1. Verify backend is running (port 8000)
  2. Check agent config has correct proxy URL with agent_type
  3. Restart MCP Gatekeeper backend
  4. Check backend logs for errors

Slow Response Times​

Problem: High latency

Solutions:

  1. Check network connection
  2. Verify server location/distance
  3. Increase timeout setting
  4. Check server performance

Best Practices​

  1. Use Descriptive Names: Name servers clearly (e.g., github-prod, openai-dev)
  2. Secure Headers: Store API tokens securely, rotate regularly
  3. Set Appropriate Timeouts: Balance between reliability and performance
  4. Monitor Metrics: Track latency and error rates
  5. Test Before Deploy: Use Test button before adding to agents
  6. Document Servers: Note what each server does and who uses it

Tested HTTP MCP Servers​

# GitHub Copilot MCP
https://api.githubcopilot.com/mcp/

Note: MCP Gatekeeper works with any HTTP MCP server that follows the MCP HTTP transport specification.

Next Steps​