Skip to main content
HTTP streaming transport allows MCP servers to communicate over HTTP rather than standard input/output (STDIO), enabling web-based clients and remote connections.

​
Overview

By default, MCP servers use STDIO transport for local communication. HTTP mode enables:
  • Remote server connections over network
  • Web-based MCP clients
  • Multiple concurrent client connections
  • Easier debugging with HTTP tools
  • Container deployments with exposed ports

​
Configuration

​
Environment Variables

Configure HTTP transport using environment variables:
VariableDescriptionDefaultRequired
ORACLE_MCP_HOSTHost address to bind to"" (disabled)Yes
ORACLE_MCP_PORTPort number to listen on"" (disabled)Yes
FASTMCP_LOG_LEVELLogging verbosityERRORNo
When ORACLE_MCP_HOST and ORACLE_MCP_PORT are set, the server automatically switches from STDIO to HTTP streaming transport.

​
Local HTTP Server

​
Start Server

Run an MCP server in HTTP mode locally: 
ORACLE_MCP_HOST=127.0.0.1 ORACLE_MCP_PORT=8888 uvx oracle.oci-api-mcp-server

​
Verify Server

Test that the server is running: 
curl http://127.0.0.1:8888/mcp
A successful response indicates the server is accepting connections.

​
Client Configuration

Configure your MCP client to connect via HTTP: 
{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8888/mcp"
    }
  }
}
The type field varies by MCP client:
  • Cline expects streamableHttp
  • Cursor, MCPHost, and most others use http
Check your client’s documentation for the correct transport type.

​
Container HTTP Server

Run an MCP server in a container with HTTP transport:

​
Using Podman

podman run \
  -v "/path/to/your/.oci:/app/.oci" \
  -e ORACLE_MCP_HOST=0.0.0.0 \
  -e ORACLE_MCP_PORT=8888 \
  -p 8888:8888 \
  oracle.oci-api-mcp-server:latest

​
Using Docker

docker run \
  -v "/path/to/your/.oci:/app/.oci" \
  -e ORACLE_MCP_HOST=0.0.0.0 \
  -e ORACLE_MCP_PORT=8888 \
  -p 8888:8888 \
  oracle.oci-api-mcp-server:latest
Key differences for containers:
  • Use ORACLE_MCP_HOST=0.0.0.0 (not 127.0.0.1) to accept external connections
  • Map container port with -p 8888:8888
  • Mount OCI credentials with -v for OCI servers

​
Client Configuration (Container)

Clients connect the same way as local servers: 
{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8888/mcp"
    }
  }
}

​
Remote Servers

​
Network Configuration

To expose an MCP server to remote clients: 
# Bind to all interfaces
ORACLE_MCP_HOST=0.0.0.0 \
ORACLE_MCP_PORT=8888 \
uvx oracle.oci-api-mcp-server
Security considerations:
  • HTTP transport does not include built-in authentication
  • Use firewall rules to restrict access
  • Consider using a reverse proxy with TLS/authentication
  • Run servers in trusted networks only
  • Never expose credentials in environment variables visible to others

​
Remote Client Configuration

{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "streamableHttp",
      "url": "http://remote-server-ip:8888/mcp"
    }
  }
}

​
Port Selection

​
Common Ports

  • 8888: Default in examples
  • 3000: Alternative common choice
  • 5000-5999: Suitable range for local services

​
Checking Port Availability

# Check if port is in use
lsof -i :8888

# Find available ports
netstat -an | grep LISTEN

​
Changing Ports

If port 8888 is already in use: 
# Use a different port
ORACLE_MCP_HOST=127.0.0.1 ORACLE_MCP_PORT=3000 uvx oracle.oci-api-mcp-server
Update client configuration accordingly: 
{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

​
Logging and Debugging

​
Enable Verbose Logging

ORACLE_MCP_HOST=127.0.0.1 \
ORACLE_MCP_PORT=8888 \
FASTMCP_LOG_LEVEL=DEBUG \
uvx oracle.oci-api-mcp-server

​
Log Levels

  • DEBUG: Detailed diagnostic information
  • INFO: General informational messages
  • WARNING: Warning messages
  • ERROR: Error messages only (default)

​
Testing HTTP Endpoints

Debug HTTP connections with curl: 
# Test connectivity
curl -v http://127.0.0.1:8888/mcp

# Check response headers
curl -I http://127.0.0.1:8888/mcp

​
Comparison: STDIO vs HTTP

FeatureSTDIOHTTP
ConnectionLocal onlyLocal or remote
ClientsSingleMultiple concurrent
SetupSimpleRequires port configuration
DebuggingLimitedHTTP tools available
SecurityProcess isolationNetwork exposure risk
PerformanceLower latencyNetwork overhead
Use caseIDE integrationsWeb apps, remote access

​
Troubleshooting

​
Server Won’t Start

Port already in use: 
Address already in use: 8888
Solution: Use a different port or stop the conflicting process.

​
Client Can’t Connect

Connection refused:
  1. Verify server is running: curl http://127.0.0.1:8888/mcp
  2. Check firewall settings
  3. Ensure correct host/port in client config
  4. For containers, verify port mapping: podman ps

​
Container Connection Issues

Can’t reach container from host:
  1. Use ORACLE_MCP_HOST=0.0.0.0 (not 127.0.0.1)
  2. Verify port mapping: -p 8888:8888
  3. Check container status: podman ps
  4. Test from inside container: podman exec <container-id> curl http://localhost:8888/mcp

​
Next Steps

Podman Deployment

Run servers in containers with Podman

Local Development

Set up local development environment

Client Configuration

Configure different MCP clients

Authentication

Set up OCI authentication

Build docs developers (and LLMs) love

Get started for freeTalk to us