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

```yaml
# 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.

```yaml
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.

```yaml
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.

```yaml
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

```bash
# 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:

```python
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:

```bash
# 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