Transport Modes - Oracle MCP Servers

Overview

MCP servers support two transport modes for client-server communication:

stdio (Standard Input/Output) - Process-based communication
HTTP Streaming - Network-based communication over HTTP

All Oracle MCP servers automatically support both modes based on environment configuration.

stdio Mode (Default)

How It Works

In stdio mode, the MCP server runs as a subprocess of the client:

┌─────────────┐
│   Client    │
│  (Cline)    │
└──────┬──────┘
       │ spawns process
       ▼
┌─────────────┐
│ MCP Server  │
│   (uvx)     │
└─────────────┘
       ▲
       │ stdin/stdout
       ▼
   JSON-RPC

The client and server communicate via JSON-RPC messages over standard input/output streams.

Configuration

Cline Configuration

{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "oracle.oci-api-mcp-server@latest"
      ],
      "env": {
        "OCI_CONFIG_PROFILE": "DEFAULT",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

From main README.md lines 155-171. The type: "stdio" field indicates stdio transport.

Cursor Configuration

Place in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "oracle.oci-api-mcp-server"
      ],
      "env": {
        "OCI_CONFIG_PROFILE": "DEFAULT",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

From main README.md lines 222-238

Advantages

Process Isolation - Each server runs in its own process

Simple Setup - No network configuration needed

Local Only - No network exposure concerns

Auto-Lifecycle - Server starts/stops with client

Limitations

Single Client - One process per client connection

Local Only - Cannot be accessed remotely

Resource Usage - Multiple clients spawn multiple processes

HTTP Streaming Mode

How It Works

In HTTP streaming mode, the MCP server runs as a standalone HTTP service:

┌─────────────┐          HTTP/SSE
│  Client 1   │◄──────────────────┐
│  (Cline)    │                   │
└─────────────┘                   │
                                  ▼
┌─────────────┐          ┌────────────────┐
│  Client 2   │◄────────►│  MCP Server    │
│  (Cursor)   │          │  (HTTP:8888)   │
└─────────────┘          └────────────────┘
                                  ▲
┌─────────────┐                   │
│  Client 3   │◄──────────────────┘
│ (Custom)    │
└─────────────┘

The server listens on a network port and handles multiple concurrent clients.

Starting the Server

Set environment variables to enable HTTP mode:

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

From main README.md lines 58-62. When ORACLE_MCP_HOST and ORACLE_MCP_PORT are set, the server automatically uses HTTP transport.

Server Implementation

All Oracle MCP servers detect the transport mode automatically:

def main():
    host = os.getenv("ORACLE_MCP_HOST")
    port = os.getenv("ORACLE_MCP_PORT")
    
    if host and port:
        mcp.run(transport="http", host=host, port=int(port))
    else:
        mcp.run()  # stdio mode (default)

From src/oci-api-mcp-server/oracle/oci_api_mcp_server/server.py:206-214 and src/oci-compute-mcp-server/oracle/oci_compute_mcp_server/server.py:419-427

Client Configuration

Cline Configuration

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

The type attribute differs across MCP clients. Cline uses streamableHttp, while other clients may use http.

From main README.md lines 63-76

Advantages

Multiple Clients - One server, many connections

Remote Access - Can be accessed over network

Resource Efficient - Shared server instance

Persistent State - Server stays running between client sessions

Security Considerations

Network Exposure - Binding to 0.0.0.0 exposes the server to your network. Use 127.0.0.1 for local-only access.

# Local only (secure)
ORACLE_MCP_HOST=127.0.0.1 ORACLE_MCP_PORT=8888 uvx oracle.oci-api-mcp-server

# Network accessible (use with caution)
ORACLE_MCP_HOST=0.0.0.0 ORACLE_MCP_PORT=8888 uvx oracle.oci-api-mcp-server

HTTP mode does not include built-in authentication. Ensure proper network security (firewalls, VPNs) when exposing servers.

Containerized HTTP Mode

Building the Container

SUBDIRS=src/oci-api-mcp-server make containerize

This creates a container image: oracle.oci-api-mcp-server:latest

Running with HTTP Transport

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

From main README.md lines 100-103

Container Credential Requirements

Ensure all file paths in ~/.oci/config use the ~ character so paths resolve correctly inside the container:

# ✓ Correct - uses ~ for home directory
key_file=~/.oci/sessions/DEFAULT/oci_api_key.pem
security_token_file=~/.oci/sessions/DEFAULT/token

# ✗ Wrong - absolute path won't work in container
key_file=/Users/myuser/.oci/sessions/DEFAULT/oci_api_key.pem
security_token_file=/Users/myuser/.oci/sessions/DEFAULT/token

From main README.md lines 104-108

Transport Mode Comparison

Feature	stdio	HTTP Streaming
Setup Complexity	Simple	Moderate
Client Limit	One per process	Multiple concurrent
Network Required	No	Yes
Resource Usage	Higher (per client)	Lower (shared)
Remote Access	No	Yes
Security	Process isolation	Network exposure
Lifecycle	Client-managed	Manual/service
Best For	Local development, single user	Shared environments, remote access

Choosing the Right Mode

Use stdio When:

✓ Developing locally with IDE extensions (Cline, Cursor) ✓ You need process isolation per client ✓ You want automatic server lifecycle management ✓ You don’t need remote access ✓ You’re following the quick start guide

Use HTTP When:

✓ Multiple users/clients need to share one server ✓ You want to deploy servers centrally ✓ You need remote access to MCP servers ✓ You’re running in a containerized environment ✓ You want to reduce resource usage

Local Development

For local development with your own server modifications:

stdio Mode

{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "oracle.oci-api-mcp-server"
      ],
      "env": {
        "VIRTUAL_ENV": "/path/to/repo/mcp/.venv",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

From main README.md lines 367-383

HTTP Mode

# Build and install locally
make build
make install

# Start server in HTTP mode
VIRTUAL_ENV=$(pwd)/.venv \
ORACLE_MCP_HOST=127.0.0.1 \
ORACLE_MCP_PORT=8888 \
uv run oracle.oci-api-mcp-server

From main README.md lines 432-441

Testing with Inspector

The MCP Inspector tool works with both modes:

stdio Mode (Default)

npx @modelcontextprotocol/inspector \
  uvx \
  oracle.oci-api-mcp-server@latest

HTTP Mode

Start the server first, then use Inspector’s HTTP client mode:

# Terminal 1: Start server
ORACLE_MCP_HOST=127.0.0.1 ORACLE_MCP_PORT=8888 \
  uvx oracle.oci-api-mcp-server

# Terminal 2: Use Inspector (check Inspector docs for HTTP support)

Next Steps

Authentication

Configure OCI credentials for both modes

Client Setup

Configure your MCP client

Local Development

Set up local development environment

Deployment

Deploy servers in production

Get Started

Core Concepts

Client Configuration

Deployment

​Overview

​stdio Mode (Default)

​How It Works

​Configuration

​Cline Configuration

​Cursor Configuration

​Advantages

​Limitations

​HTTP Streaming Mode

​How It Works

​Starting the Server

​Server Implementation

​Client Configuration

​Cline Configuration

​Advantages

​Security Considerations

​Containerized HTTP Mode

​Building the Container

​Running with HTTP Transport

​Container Credential Requirements

​Transport Mode Comparison

​Choosing the Right Mode

​Use stdio When:

​Use HTTP When:

​Local Development

​stdio Mode

​HTTP Mode

​Testing with Inspector

​stdio Mode (Default)

​HTTP Mode

​Next Steps

Authentication

Client Setup

Local Development

Deployment

Build docs developers (and LLMs) love

Overview

stdio Mode (Default)

How It Works

Configuration

Cline Configuration

Cursor Configuration

Advantages

Limitations

HTTP Streaming Mode

How It Works

Starting the Server

Server Implementation

Client Configuration

Cline Configuration

Advantages

Security Considerations

Containerized HTTP Mode

Building the Container

Running with HTTP Transport

Container Credential Requirements

Transport Mode Comparison

Choosing the Right Mode

Use stdio When:

Use HTTP When:

Local Development

stdio Mode

HTTP Mode

Testing with Inspector

stdio Mode (Default)

HTTP Mode

Next Steps