mcp-forge/docs/HTTP_TRANSPORT.md

HTTP Transport Configuration Example

This example shows how to configure MCP-Forge to connect to external HTTP-based MCP servers.

Configuration File

# config.yaml
server:
  host: localhost
  port: 3000
  podman_socket: /run/user/1000/podman/podman.sock

security:
  audit_log: ./logs/audit.log
  enforce_resource_limits: true
  allow_network: false

execution:
  default_backend: simple
  default_timeout: 300
  max_timeout: 1800
  default_memory: 512m
  max_memory: 2g
  base_image: docker.io/library/python:3.13-slim

environment_builder:
  enabled: true
  uv_cache_path: ./cache/uv
  max_packages_per_build: 50
  max_build_time: 600
  max_image_size: 2147483648
  max_concurrent_builds: 3
  build_rate_limit:
    requests: 10
    period: 60
  package_validation:
    use_allowlist: true
    allowlist_path: ./config/allowlist.txt
    blocklist_path: ./config/blocklist.txt
    require_approval_patterns: []

# Connect to external MCP servers
mcp_tools:
  # HTTP-based MCP server
  remote_api:
    transport: http
    url: http://localhost:8006/mcp
    headers:
      Authorization: "Bearer your-token-here"
      X-Custom-Header: "value"
  
  # SSE-based MCP server
  sse_service:
    transport: sse
    url: http://localhost:9000/events
    headers:
      Authorization: "Bearer your-token-here"
  
  # Traditional stdio-based MCP server (still supported)
  filesystem:
    transport: stdio  # default, can be omitted
    command: uvx
    args: [mcp-server-filesystem, /path/to/workspace]
    env:
      SOME_VAR: value

Transport Types

1. HTTP Transport

Used for HTTP-based MCP servers that communicate via HTTP requests.

remote_api:
  transport: http
  url: http://localhost:8006/mcp
  headers:
    Authorization: "Bearer token123"
    Content-Type: "application/json"

Required:

• url: HTTP endpoint URL

Optional:

• headers: HTTP headers (dict)

2. SSE Transport

Used for Server-Sent Events (SSE) based MCP servers.

sse_service:
  transport: sse
  url: http://localhost:9000/events
  headers:
    Authorization: "Bearer token123"

Required:

• url: SSE endpoint URL

Optional:

• headers: HTTP headers (dict)

3. Stdio Transport (Default)

Traditional command-based MCP servers.

filesystem:
  transport: stdio  # default, can be omitted
  command: uvx
  args: [mcp-server-filesystem, /workspace]
  env:
    PATH: /usr/bin

Required:

• command: Executable command

Optional:

• args: Command arguments (list)
• env: Environment variables (dict)

Running the Server

# Start with HTTP transport configuration
uv run mcp-forge --config config.yaml

# Or with SSE transport
uv run mcp-forge --config config.yaml --transport sse --host 0.0.0.0 --port 8080

Client Connection

Once the server is running, MCP clients can connect using the configured transport:

from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

# Connect to MCP-Forge server via HTTP
transport = StreamableHttpTransport(url="http://localhost:3000/mcp")
client = Client(transport)

async with client:
    # List available tools (from all configured MCP servers)
    tools = await client.list_tools()
    print(tools)

Testing the Connection

You can test your HTTP transport configuration using curl:

# Test HTTP endpoint
curl -X POST http://localhost:8006/mcp \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Troubleshooting

Connection Refused

• Verify the external MCP server is running
• Check the URL and port are correct
• Ensure firewall rules allow the connection

Authentication Errors

• Verify the authorization header is correct
• Check if the external server requires specific headers

Tool Not Found

• Ensure the external MCP server exposes the expected tools
• Check the server logs for any errors