Skip to main content
Run Oracle MCP servers in isolated containers using Podman for consistent, reproducible deployments.

​
Prerequisites

​
Install Podman

Follow the official Podman installation guide for your platform:

Podman Installation

Official installation instructions for Linux, macOS, and Windows
brew install podman
podman machine init
podman machine start

​
Building Container Images

​
Build All Servers

Build container images for all supported MCP servers: 
make containerize

​
Build Specific Server

Use the SUBDIRS variable to build a specific server: 
SUBDIRS=src/oci-api-mcp-server make containerize
The containerize target automatically:
  • Reads version from pyproject.toml
  • Builds the image with version tag (e.g., oracle.oci-api-mcp-server:0.1.0)
  • Creates a latest tag for convenience

​
Containerfile Structure

Each server includes a Containerfile with: 
FROM ghcr.io/oracle/oraclelinux:9-slim

# Install Python 3.13
RUN microdnf install epel-release && \
  microdnf install python3.13 python3.13-pip && \
  rm -rf /var/cache/dnf/* && \
  useradd -m -d /app oracle

# Copy server code
WORKDIR /app
COPY --chown=oracle:oracle . /app

# Install dependencies
RUN pip3.13 install --no-cache-dir uv && \
  uv --no-cache sync --locked --all-extras

USER oracle

# HTTP transport support
ENV ORACLE_MCP_HOST=""
ENV ORACLE_MCP_PORT=""

ENTRYPOINT ["uv", "run", "oracle.oci-api-mcp-server"]

​
Running Containers

​
STDIO Transport (Default)

For MCP clients that communicate via standard input/output: 
{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "stdio",
      "command": "podman",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/path/to/your/.oci:/app/.oci",
        "oracle.oci-api-mcp-server:latest"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "INFO"
      }
    }
  }
}
Important: Replace /path/to/your/.oci with your actual OCI configuration directory path:
  • macOS/Linux: ~/.oci or /Users/username/.oci
  • Windows: C:\Users\username\.oci

​
HTTP Transport

Run the server in HTTP streaming mode: 
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
Then configure your MCP client: 
{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8888/mcp"
    }
  }
}
The type attribute varies by MCP client:
  • Cline uses streamableHttp
  • Most others use http

​
OCI Configuration

​
Credential Mounting

When running OCI servers, mount your OCI configuration directory: 
podman run \
  -i --rm \
  -v "~/.oci:/app/.oci" \
  oracle.oci-api-mcp-server:latest

​
Path Resolution in Container

Ensure your ~/.oci/config file uses the ~ character for file paths to work both inside and outside the container: 
[DEFAULT]
user=ocid1.user.oc1...
fingerprint=xx:xx:xx:xx...
tenancy=ocid1.tenancy.oc1...
region=us-phoenix-1
key_file=~/.oci/sessions/DEFAULT/oci_api_key.pem
security_token_file=~/.oci/sessions/DEFAULT/token
Avoid absolute paths like /Users/myuser/.oci/... which won’t resolve inside the container. Always use ~/.oci/...

​
Servers Without OCI Credentials

For servers that don’t require OCI authentication, omit the volume mount: 
podman run -i --rm oracle.example-mcp-server:latest

​
Container Management

​
List Images

View built container images: 
podman images | grep oracle

​
Remove Images

Remove a specific image: 
podman rmi oracle.oci-api-mcp-server:latest

​
View Running Containers

podman ps

​
Stop Running Container

podman stop <container-id>

​
Troubleshooting

​
Authentication Errors

If you see OCI authentication errors:
  1. Verify the volume mount path is correct
  2. Check that ~/.oci/config uses ~ for file paths
  3. Ensure your OCI session hasn’t expired: 
    oci session authenticate --profile-name DEFAULT --region us-phoenix-1 --auth security_token

​
Permission Errors

If you encounter permission issues: 
# Verify file ownership
ls -la ~/.oci/

# Container runs as 'oracle' user with UID/GID from host
podman run --user $(id -u):$(id -g) ...

​
Connection Errors (HTTP Mode)

If the client can’t connect to HTTP endpoint:
  1. Verify the container is running: podman ps
  2. Check port mapping: -p 8888:8888
  3. Ensure ORACLE_MCP_HOST=0.0.0.0 (not 127.0.0.1)
  4. Test connectivity: curl http://127.0.0.1:8888/mcp

​
Next Steps

HTTP Mode

Learn more about HTTP transport configuration

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