How do I use MCP OCI OPSI Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP OCI OPSI Server Show me a summary of my database fleet and highlight any performance issues." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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 Summary

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:

Database List

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

Database Details

Get detailed information about any specific database:

Database Details

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

What's New in v3.0

Feature	Description
OCI IAM OAuth	Enterprise authentication with OCI Identity Domains
API Key Fallback	Seamless fallback to ~/.oci/config for development
MCP Resources	10 read-only data endpoints for efficient access
MCP Prompts	15 guided DBA workflow templates
Server Composition	4 modular sub-servers with tool prefixes
DBA Skills	13 specialized skills for token-efficient workflows
Di[Link to Secure Variable: OPENAI_API_KEY] Storage	No Redis required - encrypted file storage
OCI VM Ready	Terraform scripts for automated deployment
Async Tasks	Background cache builds (`cache_start_cache_build_task`) with polling
Prebuilt Playbooks	`admin_get_troubleshooting_playbook` and `admin_list_prompts` for fast LLM guidance

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)

Prefix	Server	Description
`cache_`	cache-tools	Instant operations (zero API calls) and async cache build tasks
`opsi_`	opsi-tools	Operations Insights analytics with pagination and rate-limit hints
`dbm_`	dbm-tools	Database Management operations with pagination
`admin_`	admin-tools	Profile/config, health, prompts, troubleshooting playbook
(prompts)	admin-tools	`admin_list_prompts`, `admin_get_troubleshooting_playbook`

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

Python 3.10+
OCI CLI configured at ~/.oci/config

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](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)

Tool	Description
`cache_get_fleet_summary`	Fleet overview with counts and types
`cache_search_databases`	Search by name, type, compartment
`cache_get_databases_by_compartment`	List databases in compartment
`cache_get_cached_statistics`	Cache metadata and stats
`cache_list_cached_compartments`	All compartments in cache
`cache_build_database_cache`	Build/rebuild cache
`cache_refresh_cache_if_needed`	Check and refresh cache
`cache_get_database_by_id`	Get database by OCID

Database Search:

Database Details:

OPSI Tools (Operations Insights)

Tool	Description
`opsi_list_database_insights`	List database insights
`opsi_summarize_sql_statistics`	SQL performance metrics
`opsi_summarize_sql_insights`	SQL anomaly detection
`opsi_get_database_capacity_trend`	Historical capacity
`opsi_get_database_resource_forecast`	ML forecasting
`opsi_list_host_insights`	Host monitoring
`opsi_list_exadata_insights`	Exadata monitoring
`opsi_query_warehouse`	OPSI warehouse SQL
`opsi_summarize_addm_findings`	ADDM analysis

DBM Tools (Database Management)

Tool	Description
`dbm_list_managed_databases`	List managed databases
`dbm_get_managed_database`	Database details
`dbm_get_tablespace_usage`	Storage metrics
`dbm_list_awr_snapshots`	AWR snapshots
`dbm_get_awr_report`	Generate AWR report
`dbm_get_addm_report`	ADDM recommendations
`dbm_list_sql_plan_baselines`	SPM baselines
`dbm_get_database_parameters`	DB parameters

Admin Tools

Tool	Description
`admin_ping`	Health check
`admin_whoami`	Current context
`admin_list_profiles`	OCI profiles
`admin_validate_profile`	Validate config
`admin_switch_profile`	Change profile
`admin_get_auth_status`	Auth mode info
`admin_diagnose_permissions`	Permission check
`admin_generate_oauth_keys`	Generate keys
`admin_list_compartments`	Compartment tree
`admin_get_tenancy_info`	Tenancy details

Skills Tools

Tool	Description
`list_available_skills`	List 13 DBA skills
`get_skill_context`	Get skill instructions
`get_skill_for_query`	Auto-match skill
`get_quick_reference`	Ta[Link to Secure Variable: OPENAI_API_KEY] mapping
`get_token_optimization_tips`	Best practices

MCP Resources

Access read-only data via URI patterns:

Resource URI	Description
`resource://fleet/summary`	Fleet overview
`resource://fleet/statistics`	Detailed stats
`resource://fleet/compartments`	Compartment list
`resource://database/{id}`	Database info
`resource://database/{id}/tablespaces`	Tablespace usage
`resource://config/profiles`	OCI profiles
`resource://config/current`	Current config
`resource://auth/status`	Auth status
`resource://welcome`	Getting started

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:

Skill	Description	Key Tools
`fleet-overview`	Fleet inventory and health	cache_get_fleet_summary
`sql-performance`	SQL analysis and tuning	opsi_summarize_sql_statistics
`capacity-planning`	Forecasting and trends	opsi_get_database_resource_forecast
`database-diagnostics`	ADDM and troubleshooting	dbm_get_addm_report
`awr-analysis`	AWR reports and snapshots	dbm_get_awr_report
`host-monitoring`	Host resource monitoring	opsi_list_host_insights
`storage-management`	Tablespace monitoring	dbm_get_tablespace_usage
`security-audit`	User and privilege audit	admin_diagnose_permissions
`sql-watch-management`	SQL Watch configuration	opsi tools
`sql-plan-baselines`	SPM management	dbm_list_sql_plan_baselines
`multi-tenancy`	Profile management	admin_list_profiles
`exadata-monitoring`	Exadata insights	opsi_list_exadata_insights
`dba-assistant`	General DBA help	all tools

Configuration

Environment Variables

Variable	Default	Description
`MCP_VERSION`	`v2`	Entry mode (v2 = MCP server, v3 = bootstrap/CLI)
`MCP_TRANSPORT`	`stdio`	Transport (stdio, http, sse, streamable-http)
`MCP_HOST`	`0.0.0.0`	Bind address for network transports
`MCP_PORT`	`8000`	Port for network transports
`MCP_HTTP_HOST`	`0.0.0.0`	Legacy HTTP bind address (fallback)
`MCP_HTTP_PORT`	`8000`	Legacy HTTP port (fallback)
`OCI_CLI_PROFILE`	`DEFAULT`	OCI profile name
`OCI_REGION`	from config	Region override
`FASTMCP_OAUTH_ENABLED`	`0`	Enable OAuth
`JWT_SIGNING_KEY`	-	JWT signing key (OAuth)
`STORAGE_ENCRYPTION_KEY`	-	Token encryption key
`OTEL_TRACING_ENABLED`	`true`	Enable OpenTelemetry tracing
`OCI_APM_ENDPOINT`	-	OCI APM OTLP endpoint ([Link to Secure Variable: OCI_APM_ENDPOINT])
`OCI_APM_PRIVATE_DATA_KEY`	-	OCI APM private data key ([Link to Secure Variable: OCI_APM_PRIVATE_DATA_KEY])
`OTEL_EXPORTER_OTLP_ENDPOINT`	-	Generic OTLP endpoint (HTTP or gRPC)
`OTEL_DISABLE_LOCAL`	`false`	Disable local collector fallback

OAuth Configuration (Production)

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

Documentation

Document	Description
FASTMCP_V3_GUIDE.md	Complete v3.0 guide
SKILLS_GUIDE.md	DBA skills reference
docs/OCI_VM_DEPLOYMENT.md	OCI VM deployment
docs/ARCHITECTURE.md	Detailed architecture
CACHE_SYSTEM.md	Cache system docs
SECURITY.md	Security guidelines

MCP OCI OPSI Server

Standards

Screenshots

Fleet Summary - Instant Overview

Database Search Results

Database Details

What's New in v3.0

Startup & Transports

Architecture Overview

High-Level Architecture

Tool Organization (v3.0)

Authentication Flow

Prerequisites

Prompts & Playbooks

Installation

Quick Install (Development)

Production Install (Docker)

Quick Start

1. Build the Cache (Recommended)

2. Configure MCP Client (stdio)

3. HTTP Transport (remote)

4. Start Using

What Gets Provisioned

Detailed Guide

Available Tools

Cache Tools (Instant - Zero API Calls)

OPSI Tools (Operations Insights)

DBM Tools (Database Management)

Admin Tools

Skills Tools

MCP Resources

MCP Prompts

Analysis Prompts

Operations Prompts

Reporting Prompts

DBA Skills

Configuration

Environment Variables

OAuth Configuration (Production)

Documentation

License

Contributing

Resources

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API