Authentication - Oracle MCP Servers

Overview

Oracle MCP servers that interact with OCI services require proper authentication. The servers use the OCI CLI configuration and support two primary authentication methods:

Session Token Authentication (Recommended)
API Key Authentication (For services requiring persistent access)

All MCP server actions are performed with the permissions of the configured OCI CLI profile. Follow least-privilege principles and secure credential management practices.

Prerequisites

Before configuring authentication:

Active Oracle Cloud Infrastructure (OCI) account
Appropriate IAM permissions in your tenancy
Terminal/command-line access

Session Token Authentication

Session tokens provide temporary, time-limited authentication and are the recommended method for most use cases.

Installing OCI CLI

Install the OCI CLI following the official documentation:

# macOS/Linux
bash -c "$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)"

# Windows (PowerShell)
powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.ps1'))"

Initial Authentication

Authenticate using session tokens:

oci session authenticate --region=<region> --tenancy-name=<tenancy_name>

Where:

<region> - Your OCI region (e.g., us-phoenix-1, us-ashburn-1)
<tenancy_name> - Your OCI tenancy name

From main README.md lines 116-122

Example:

oci session authenticate --region=us-phoenix-1 --tenancy-name=mycompany

This command will:

Open a browser for authentication
Create a session token
Configure your ~/.oci/config file
Store credentials in ~/.oci/sessions/

Configuration File Structure

After authentication, your ~/.oci/config looks like:

[DEFAULT]
region=us-phoenix-1
tenancy=ocid1.tenancy.oc1...
user=ocid1.user.oc1...
fingerprint=a1:b2:c3:...
key_file=~/.oci/sessions/DEFAULT/oci_api_key.pem
security_token_file=~/.oci/sessions/DEFAULT/token

The profile name (DEFAULT above) can be customized. You can have multiple profiles for different tenancies or users.

Refreshing Expired Sessions

Session tokens expire after a period (typically 1 hour). Refresh them with:

oci session authenticate --profile-name <profile_name> --region <region> --auth security_token

Example:

oci session authenticate --profile-name DEFAULT --region us-phoenix-1 --auth security_token

From main README.md lines 127-130

Session Token Implementation

MCP servers load session tokens programmatically:

def get_compute_client():
    config = oci.config.from_file(
        file_location=os.getenv("OCI_CONFIG_FILE", oci.config.DEFAULT_LOCATION),
        profile_name=os.getenv("OCI_CONFIG_PROFILE", oci.config.DEFAULT_PROFILE),
    )
    
    # Load private key
    private_key = oci.signer.load_private_key_from_file(config["key_file"])
    
    # Load session token
    token_file = os.path.expanduser(config["security_token_file"])
    with open(token_file, "r") as f:
        token = f.read()
    
    # Create token signer
    signer = oci.auth.signers.SecurityTokenSigner(token, private_key)
    
    return oci.core.ComputeClient(config, signer=signer)

From src/oci-compute-mcp-server/oracle/oci_compute_mcp_server/server.py:38-53

API Key Authentication

Some MCP servers may not work with token-based authentication alone and require API key authentication for persistent access.

When to Use API Keys

Long-running services that need unattended operation

Servers that access resources requiring persistent authentication

Automated workflows that can’t refresh session tokens

Generating API Keys

Follow the OCI API key documentation to:

Generate an RSA key pair
Upload the public key to your OCI user settings
Configure your ~/.oci/config file

Example configuration:

[API_KEY_PROFILE]
user=ocid1.user.oc1...
fingerprint=a1:b2:c3:...
tenancy=ocid1.tenancy.oc1...
region=us-phoenix-1
key_file=~/.oci/oci_api_key.pem

From main README.md line 124. API key setup details are in the linked OCI documentation.

Profile Configuration

Viewing Available Profiles

List all configured profiles:

cat ~/.oci/config

You’ll see sections like [DEFAULT], [PROFILE1], [PROFILE2], etc.

From main README.md line 132

Specifying a Profile

MCP servers use the OCI_CONFIG_PROFILE environment variable:

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

From main README.md lines 164-167

Multiple Profiles Example

# Development environment
[DEVELOPMENT]
region=us-phoenix-1
tenancy=ocid1.tenancy.oc1...dev
user=ocid1.user.oc1...dev
key_file=~/.oci/sessions/DEVELOPMENT/oci_api_key.pem
security_token_file=~/.oci/sessions/DEVELOPMENT/token

# Production environment
[PRODUCTION]
region=us-ashburn-1
tenancy=ocid1.tenancy.oc1...prod
user=ocid1.user.oc1...prod
key_file=~/.oci/sessions/PRODUCTION/oci_api_key.pem
security_token_file=~/.oci/sessions/PRODUCTION/token

Container Authentication

When running MCP servers in containers, mount your OCI configuration:

Podman/Docker Configuration

podman run -i --rm \
  -v "/path/to/your/.oci:/app/.oci" \
  oracle.oci-api-mcp-server:latest

From main README.md line 184

Path Resolution Requirements

Critical: All file paths in your ~/.oci/config must use the ~ character for proper resolution inside containers.

Correct configuration:

[DEFAULT]
key_file=~/.oci/sessions/DEFAULT/oci_api_key.pem
security_token_file=~/.oci/sessions/DEFAULT/token

Incorrect configuration:

[DEFAULT]
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 195-196 and lines 104-108

Security Best Practices

Least Privilege Access

All actions are performed with the permissions of the configured OCI CLI profile. We strongly advise:

Least-privilege IAM setup - Grant only required permissions
Secure credential management - Protect your ~/.oci/ directory
Safe network practices - Use secure networks for API calls
Secure logging - Avoid logging sensitive credentials
Never expose secrets - Don’t commit credentials to source control

From main README.md lines 124-126

File Permissions

Secure your OCI configuration:

# Restrict access to OCI config directory
chmod 700 ~/.oci

# Restrict access to private keys
chmod 600 ~/.oci/sessions/*/oci_api_key.pem

# Restrict access to tokens
chmod 600 ~/.oci/sessions/*/token

Credential Rotation

Regularly refresh session tokens (they expire automatically)

Rotate API keys periodically

Audit IAM policies regularly

Remove unused profiles and keys

Authentication Troubleshooting

Common Issues

”Session token expired"

# Refresh the token
oci session authenticate --profile-name DEFAULT --region us-phoenix-1 --auth security_token

"Config file not found"

# Verify config location
ls -la ~/.oci/config

# Set custom location if needed
export OCI_CONFIG_FILE=/path/to/custom/config

"Permission denied on private key"

# Fix file permissions
chmod 600 ~/.oci/sessions/DEFAULT/oci_api_key.pem

"Profile not found”

# List available profiles
cat ~/.oci/config | grep "\[.*\]"

# Use correct profile name
export OCI_CONFIG_PROFILE=CORRECT_PROFILE_NAME

Verifying Authentication

Test your OCI authentication:

# Test default profile
oci iam region list

# Test specific profile
oci iam region list --profile PRODUCTION

# Test with token authentication
oci iam region list --profile DEFAULT --auth security_token

Environment Variables Reference

Variable	Description	Default
`OCI_CONFIG_FILE`	Path to OCI config file	`~/.oci/config`
`OCI_CONFIG_PROFILE`	Profile name to use	`DEFAULT`
`ORACLE_MCP_HOST`	HTTP mode: server host	None (stdio mode)
`ORACLE_MCP_PORT`	HTTP mode: server port	None (stdio mode)
`FASTMCP_LOG_LEVEL`	Logging verbosity	`INFO`

MCP Client Configuration Examples

Cline with Custom Profile

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

MCPHost with Custom Config

OCI_CONFIG_PROFILE=PRODUCTION \
OCI_CONFIG_FILE=/custom/path/config \
mcphost -m ollama:llama3.2 --config ~/.mcphost.json

From main README.md lines 340

Next Steps

Quick Start

Install and run your first MCP server

Client Setup

Configure your MCP client

Available Servers

Browse all available MCP servers

Security Guide

Learn more about security best practices

Get Started

Core Concepts

Client Configuration

Deployment

​Overview

​Prerequisites

​Session Token Authentication

​Installing OCI CLI

​Initial Authentication

​Configuration File Structure

​Refreshing Expired Sessions

​Session Token Implementation

​API Key Authentication

​When to Use API Keys

​Generating API Keys

​Profile Configuration

​Viewing Available Profiles

​Specifying a Profile

​Multiple Profiles Example

​Container Authentication

​Podman/Docker Configuration

​Path Resolution Requirements

​Security Best Practices

​Least Privilege Access

​File Permissions

​Credential Rotation

​Authentication Troubleshooting

​Common Issues

​”Session token expired"

​"Config file not found"

​"Permission denied on private key"

​"Profile not found”

​Verifying Authentication

​Environment Variables Reference

​MCP Client Configuration Examples

​Cline with Custom Profile

​MCPHost with Custom Config

​Next Steps

Quick Start

Client Setup

Available Servers

Security Guide

Build docs developers (and LLMs) love

Overview

Prerequisites

Session Token Authentication

Installing OCI CLI

Initial Authentication

Configuration File Structure

Refreshing Expired Sessions

Session Token Implementation

API Key Authentication

When to Use API Keys

Generating API Keys

Profile Configuration

Viewing Available Profiles

Specifying a Profile

Multiple Profiles Example

Container Authentication

Podman/Docker Configuration

Path Resolution Requirements

Security Best Practices

Least Privilege Access

File Permissions

Credential Rotation

Authentication Troubleshooting

Common Issues

”Session token expired"

"Config file not found"

"Permission denied on private key"

"Profile not found”

Verifying Authentication

Environment Variables Reference

MCP Client Configuration Examples

Cline with Custom Profile

MCPHost with Custom Config

Next Steps