MCP OCI OPSI Server

Version 3.0 | FastMCP 2.0 | 13 DBA Skills | OAuth + API Key Auth | Multi-Tenancy

MCP (Model Context Protocol) server for Oracle Cloud Infrastructure (OCI) Operations Insights. This server provides comprehensive Oracle database monitoring and analysis capabilities through Claude Desktop, Claude Code, ChatGPT, or any MCP-compatible client (stdio or HTTP transports).

Quick Links: Installation | Quick Start | Startup & Transports | Prompts & Playbooks | OCI VM Deployment | API Reference

Guides: Skills Guide | FastMCP v3 Guide | OCI Deployment Guide

Standards

• docs/OCI_MCP_SERVER_STANDARD.md

Screenshots

Fleet Summary - Instant Overview

Get a complete overview of your database fleet with zero API calls:

Fleet overview showing database counts, types, and compartment distribution - instant response from local cache

Database Search Results

Search and discover databases across your tenancy instantly:

Comprehensive database list with OCIDs, types, and compartments - cached for instant queries

Database Details

Get detailed information about any specific database:

Detailed database information including OCID, type, compartment, and status - instant lookup from cache

What's New in v3.0

Startup & Transports

• stdio (default): python -m mcp_oci_opsi (best for Claude Desktop/Code, ChatGPT MCP).
• HTTP: MCP_TRANSPORT=http MCP_PORT=8000 python -m mcp_oci_opsi (for remote clients).
• SSE / Streamable HTTP: MCP_TRANSPORT=sse|streamable-http MCP_PORT=8000 python -m mcp_oci_opsi (if supported by your FastMCP runtime).
• Version switch: MCP_VERSION=v2 (FastMCP server). MCP_VERSION=v3 runs a local bootstrap/CLI (not an MCP server).
• Logging: Set LOG_LEVEL=DEBUG for verbose startup; OCI SDK logs default to WARNING.
• Timeouts: OCI_CLIENT_TIMEOUT, OPSI_CLIENT_TIMEOUT, DBM_CLIENT_TIMEOUT (seconds) bound per-call latency; MCP_CLIENT_TIMEOUT_MS caps tool invocations.

Architecture Overview

High-Level Architecture

                                    ┌─────────────────────────────────────┐
                                    │         MCP Clients                 │
                                    │  (Claude Desktop/Code, ChatGPT)     │
                                    └──────────────┬──────────────────────┘
                                                   │
                                    MCP Protocol (stdio/HTTP)
                                                   │
┌──────────────────────────────────────────────────┴──────────────────────────────────────────────────┐
│                                                                                                      │
│                              MCP OCI OPSI SERVER v3.0                                               │
│                                                                                                      │
│  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│  │                                    FastMCP 2.0 Core                                            │ │
│  │                                                                                                │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │ │
│  │  │   cache_*   │  │   opsi_*    │  │    dbm_*    │  │   admin_*   │  │    Skills Engine    │  │ │
│  │  │   8 tools   │  │   9 tools   │  │   8 tools   │  │  10 tools   │  │    13 DBA skills    │  │ │
│  │  │  4 resources│  │  1 resource │  │  2 resources│  │  3 resources│  │                     │  │ │
│  │  │             │  │             │  │             │  │             │  │  • Fleet Overview   │  │ │
│  │  │ Zero API    │  │ Operations  │  │  Database   │  │   Profile   │  │  • SQL Performance  │  │ │
│  │  │   calls     │  │  Insights   │  │ Management  │  │   Config    │  │  • Capacity Plan    │  │ │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────────────┘  │ │
│  │                                                                                                │ │
│  │  ┌─────────────────────────────────────────────────────────────────────────────────────────┐  │ │
│  │  │                              15 MCP Prompts (Workflow Templates)                        │  │ │
│  │  │  Analysis: analyze_database_performance, investigate_slow_query, analyze_wait_events   │  │ │
│  │  │  Operations: enable_monitoring, security_audit, tablespace_maintenance                 │  │ │
│  │  │  Reporting: capacity_planning_report, fleet_inventory_report, compliance_report        │  │ │
│  │  └─────────────────────────────────────────────────────────────────────────────────────────┘  │ │
│  └────────────────────────────────────────────────────────────────────────────────────────────────┘ │
│                                                                                                      │
│  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│  │                                  Authentication Layer                                          │ │
│  │                                                                                                │ │
│  │  ┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────────────────────┐   │ │
│  │  │    OCI IAM OAuth    │  │    API Key Auth     │  │     Resource Principal (Future)     │   │ │
│  │  │  (Production/HTTP)  │  │  (Development/stdio)│  │     (OCI Functions/Containers)      │   │ │
│  │  │                     │  │                     │  │                                     │   │ │
│  │  │  • OIDC Proxy       │  │  • ~/.oci/config    │  │  • Instance metadata auth           │   │ │
│  │  │  • Token Exchange   │  │  • Profile support  │  │  • Dynamic credentials              │   │ │
│  │  │  • Disk storage     │  │  • Multi-tenancy    │  │  • Auto-rotation                    │   │ │
│  │  └─────────────────────┘  └─────────────────────┘  └─────────────────────────────────────┘   │ │
│  └────────────────────────────────────────────────────────────────────────────────────────────────┘ │
│                                                                                                      │
│  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│  │                                    OCI SDK Client Layer                                        │ │
│  │  • Operations Insights Client    • Database Management Client    • Identity Client             │ │
│  │  • Client caching (16 clients)   • Multi-region support          • Automatic pagination        │ │
│  └────────────────────────────────────────────────────────────────────────────────────────────────┘ │
│                                                                                                      │
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘
                                                   │
                                    HTTPS REST API Calls
                                    (Regional endpoints)
                                                   │
┌──────────────────────────────────────────────────┴──────────────────────────────────────────────────┐
│                                                                                                      │
│                                 ORACLE CLOUD INFRASTRUCTURE                                          │
│                                                                                                      │
│  ┌──────────────────────────┐  ┌──────────────────────────┐  ┌──────────────────────────┐           │
│  │  Operations Insights     │  │  Database Management     │  │      Identity            │           │
│  │                          │  │                          │  │                          │           │
│  │  • Host Insights         │  │  • Managed Databases     │  │  • Users & Groups        │           │
│  │  • Database Insights     │  │  • SQL Plan Baselines    │  │  • Compartments          │           │
│  │  • SQL Statistics        │  │  • Performance Hub       │  │  • Policies              │           │
│  │  • Capacity Planning     │  │  • ADDM / AWR            │  │  • Identity Domains      │           │
│  │  • ML Forecasting        │  │  • Tablespaces           │  │                          │           │
│  └──────────────────────────┘  └──────────────────────────┘  └──────────────────────────┘           │
│                                                                                                      │
│  Regional Endpoints: operationsinsights.{region}.oci.oraclecloud.com                                │
│                      database.{region}.oraclecloud.com                                               │
│                      identity.{region}.oci.oraclecloud.com                                           │
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘

Tool Organization (v3.0)

Authentication Flow

┌────────────────────────────────────────────────────────────────────────────────┐
│                           Authentication Decision Tree                          │
└────────────────────────────────────────────────────────────────────────────────┘
                                       │
                    ┌──────────────────┴──────────────────┐
                    ▼                                      ▼
        ┌─────────────────────┐              ┌─────────────────────┐
        │  HTTP Transport?    │              │  stdio Transport    │
        │  (Production)       │              │  (Development)      │
        └──────────┬──────────┘              └──────────┬──────────┘
                   │                                    │
        ┌──────────┴──────────┐                        │
        ▼                      ▼                        ▼
┌───────────────┐    ┌───────────────┐        ┌───────────────────┐
│ OAuth Enabled │    │ OAuth Not     │        │  API Key Auth     │
│ (FASTMCP_     │    │ Configured    │        │  ~/.oci/config    │
│  OAUTH=1)     │    │               │        │                   │
└───────┬───────┘    └───────┬───────┘        └─────────┬─────────┘
        │                    │                          │
        ▼                    ▼                          ▼
┌───────────────────────────────────────────────────────────────────┐
│                        OCI API Calls                               │
│  • Signed requests with user/tenancy context                      │
│  • Regional endpoint routing                                       │
│  • Automatic retry and error handling                             │
└───────────────────────────────────────────────────────────────────┘

Prerequisites

1. Python 3.10+
2. OCI CLI configured at ~/.oci/config
3. Required IAM Policies:

   Allow group YourGroup to read operations-insights-family in tenancy
   Allow group YourGroup to read database-management-family in tenancy
   Allow group YourGroup to read compartments in tenancy
   

Prompts & Playbooks

• Prompt templates: admin_list_prompts returns prebuilt instructions for CPU hotspots, storage risk, slow SQL, and fleet overview. Use as canned system prompts for any LLM.
• Troubleshooting playbook: admin_get_troubleshooting_playbook(issue?) suggests cache-first tool flows with reasons.
• Health checks: admin_ping, opsi_health, dbm_health are zero-cost readiness probes.
• Async tasks: Kick off cache builds with cache_start_cache_build_task(compartment_ids=[...]) and poll with cache_get_task_status(task_id=...).

Installation

Quick Install (Development)

# Clone repository
git clone https://github.com/adibirzu/mcp_oci_opsi.git
cd mcp_oci_opsi

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .

# Verify installation
python -c "from mcp_oci_opsi.main_v3 import app; print('OK')"

Production Install (Docker)

# Build image
docker build -t mcp-oci-opsi .

# Run with stdio transport
docker run -it --rm \
  -v ~/.oci:/home/mcp/.oci:ro \
  mcp-oci-opsi

# Run with HTTP transport
docker run -d \
  -p 8000:8000 \
  -v ~/.oci:/home/mcp/.oci:ro \
  -e MCP_TRANSPORT=http \
  mcp-oci-opsi

Quick Start

1. Build the Cache (Recommended)

# One-time setup - builds local cache for instant queries
./scripts/setup_and_build.sh

# Or with specific profile
./scripts/setup_and_build.sh --profile PRODUCTION

2. Configure MCP Client (stdio)

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) or ChatGPT MCP:

{
  "mcpServers": {
    "oci-opsi": {
      "command": "/path/to/mcp_oci_opsi/.venv/bin/python",
      "args": ["-m", "mcp_oci_opsi"],
      "env": {
        "MCP_VERSION": "v3",
        "OCI_CLI_PROFILE": "DEFAULT"
      }
    }
  }
}

3. HTTP Transport (remote)

export MCP_TRANSPORT=http
export MCP_HTTP_PORT=8000
python -m mcp_oci_opsi

ChatGPT MCP (HTTP)

{
  "mcpServers": {
    "oci-opsi": {
      "url": "http://127.0.0.1:8000"
    }
  }
}

4. Start Using

# Instant queries (from cache)
"How many databases do I have?"
"Find database PRODDB01"
"Show fleet summary"

# Real-time analytics (API calls)
"Analyze SQL performance for the last 24 hours"
"Show CPU forecast for next 30 days"
"Generate ADDM report for database X"

# Guided workflows (skills)
"Use the sql-performance skill to analyze slow queries"
"Run daily health check"

### 5. Run tests

```bash
cd mcp_oci_opsi
python -m pytest

#### Example: Fleet Summary Response

Ask "Show me a summary of my database fleet" and get instant results:

![Fleet Summary Example](https://raw.githubusercontent.com/adibirzu/mcp_oci_opsi/main/Screenshots/fleet.png)

---

## OCI VM Deployment

Deploy to OCI Compute with automated provisioning using Terraform.

### Quick Deploy

```bash
cd terraform/oci-vm

# Configure variables
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your values

# Deploy
terraform init
terraform plan
terraform apply

# Get connection info
terraform output

What Gets Provisioned

• OCI Compute Instance (VM.Standard.E4.Flex, 2 OCPU, 16GB RAM)
• VCN with Subnet (public or private)
• Security Lists (SSH + optional HTTP)
• Cloud-Init Provisioning:
  • Python 3.11 + pip
  • Docker + Docker Compose
  • MCP OCI OPSI Server
  • OCI CLI
  • Systemd service for auto-start

Detailed Guide

See docs/OCI_VM_DEPLOYMENT.md for:

• Step-by-step instructions
• Network configuration options
• Security hardening
• OAuth setup for production
• Monitoring and maintenance

Available Tools

Cache Tools (Instant - Zero API Calls)

OPSI Tools (Operations Insights)

DBM Tools (Database Management)

Admin Tools

Skills Tools

MCP Resources

Access read-only data via URI patterns:

MCP Prompts

Reusable workflow templates:

Analysis Prompts

• analyze_database_performance(database_name, time_range)
• investigate_slow_query(sql_id)
• analyze_wait_events(database_name, wait_class)
• analyze_resource_contention(compartment_name)
• daily_health_check()

Operations Prompts

• enable_monitoring(compartment_name)
• security_audit(compartment_name)
• tablespace_maintenance(database_name)
• plan_baseline_management(database_name)
• profile_setup(profile_name)

Reporting Prompts

• capacity_planning_report(compartment_name, forecast_days)
• performance_summary_report(database_name, days)
• fleet_inventory_report()
• awr_comparison_report(database_name, baseline, compare)
• compliance_report(compartment_name)

DBA Skills

13 specialized skills for common DBA tasks:

Configuration

Environment Variables

OAuth Configuration (Production)

See FASTMCP_V3_GUIDE.md for OAuth setup with OCI Identity Domains.

Documentation

License

MIT

Contributing

Contributions welcome! Please see CONTRIBUTING.md.

Resources

• Model Context Protocol
• FastMCP Documentation
• OCI Operations Insights
• OCI Python SDK