Skip to main content
The OCI Cloud MCP server provides generic tools to interact with Oracle Cloud Infrastructure services using the official OCI Python SDK directly. This server enables invoking any OCI SDK client operation without requiring service-specific MCP servers.

​
Installation

uvx oracle.oci-cloud-mcp-server

​
Running the Server

​
STDIO Transport Mode

uvx oracle.oci-cloud-mcp-server

​
HTTP Streaming Transport Mode

ORACLE_MCP_HOST=<hostname/IP address> ORACLE_MCP_PORT=<port number> uvx oracle.oci-cloud-mcp-server

​
Available Tools

The server provides generic tools for SDK operations:
Tool NameDescription
invoke_oci_apiInvoke an OCI Python SDK API via client and operation name
list_client_operationsList public callable operations for a given OCI client class

​
Tool Details

​
invoke_oci_api

Invoke any OCI SDK operation by specifying the client class and operation name. Parameters:
  • client_fqn (required) - Fully-qualified client class name (e.g., oci.core.ComputeClient)
  • operation (required) - Client method/operation name (e.g., list_instances)
  • params (required) - JSON object of keyword arguments as expected by the SDK method
Example: 
{
  "client_fqn": "oci.core.ComputeClient",
  "operation": "list_instances",
  "params": {
    "compartment_id": "ocid1.compartment.oc1..exampleuniqueID"
  }
}
Response: 
{
  "client": "oci.core.ComputeClient",
  "operation": "list_instances",
  "params": { "compartment_id": "ocid1..." },
  "opc_request_id": "abcd-efgh-...",
  "data": [ /* JSON-serialized SDK response data */ ]
}

​
list_client_operations

Discover available operations for an OCI client. Parameters:
  • client_fqn (required) - Fully-qualified client class name (e.g., oci.identity.IdentityClient)
Returns: List of operations with short summaries extracted from docstrings when available.

​
Usage Examples

​
List Compute Instances

List all compute instances in compartment ocid1.compartment.oc1..example using the SDK
The AI will use invoke_oci_api with:
  • client_fqn: oci.core.ComputeClient
  • operation: list_instances
  • params: {"compartment_id": "ocid1.compartment.oc1..example"}

​
Create a VCN

Create a VCN with CIDR 10.0.0.0/16 using the SDK
The AI will construct the appropriate SDK call with oci.core.VirtualNetworkClient and create_vcn operation.

​
Discover Operations

What operations are available for IdentityClient?
Uses list_client_operations with client_fqn: "oci.identity.IdentityClient".

​
Complex Model Parameters

Create a VCN with display name "production-vcn" and DNS label "prodvcn"
The server automatically constructs SDK model objects (e.g., CreateVcnDetails) from the provided JSON parameters.

​
Understanding the OCI SDK

​
What is the OCI SDK?

The OCI Python SDK provides programmatic access to Oracle Cloud Infrastructure:
  • Comprehensive - Covers all OCI services
  • Type-Safe - Strongly typed models
  • Well-Documented - Extensive docstrings
  • Maintained - Regularly updated by Oracle
  • Pythonic - Follows Python conventions

​
SDK Structure

Clients
  • Service-specific clients (e.g., ComputeClient, VirtualNetworkClient)
  • Handle authentication and API requests
  • Provide operation methods
Models
  • Data transfer objects
  • Request/response models
  • Configuration objects
Pagination
  • Automatic pagination for list operations
  • Iterator-based result handling

​
Common Client Classes

Compute & Storage
  • oci.core.ComputeClient - Compute instances
  • oci.core.BlockstorageClient - Block volumes
  • oci.object_storage.ObjectStorageClient - Object storage
Networking
  • oci.core.VirtualNetworkClient - VCNs, subnets, security
  • oci.load_balancer.LoadBalancerClient - Load balancers
  • oci.network_load_balancer.NetworkLoadBalancerClient - Network LB
Database
  • oci.database.DatabaseClient - Database services
Identity
  • oci.identity.IdentityClient - IAM operations
Monitoring & Management
  • oci.monitoring.MonitoringClient - Metrics and alarms
  • oci.logging.LoggingManagementClient - Logging
  • oci.cloud_guard.CloudGuardClient - Cloud Guard

​
Passing Complex Model Parameters

Many OCI SDK operations expect complex model instances (e.g., CreateVcnDetails) rather than raw dictionaries.

​
Automatic Model Construction

The server automatically constructs SDK model objects from JSON parameters using heuristics: Parameter name patterns:
  • Ends with _details (e.g., create_vcn_details)
  • Ends with _config
  • Ends with _configuration
  • Ends with _source_details
Example: 
{
  "client_fqn": "oci.core.VirtualNetworkClient",
  "operation": "create_vcn",
  "params": {
    "create_vcn_details": {
      "cidr_block": "10.0.0.0/16",
      "compartment_id": "ocid1.compartment.oc1..example",
      "display_name": "my-vcn"
    }
  }
}
The server constructs an instance of oci.core.models.CreateVcnDetails automatically.

​
Verb-Prefixed Parameters

For create_* and update_* operations, if the parameter is named like vcn_details (missing the verb), the server will try CreateVcnDetails/UpdateVcnDetails automatically.

​
Explicit Model Hints

You can provide explicit type hints: __model - Simple class name in the client’s models module: 
{
  "create_vcn_details": {
    "__model": "CreateVcnDetails",
    "cidr_block": "10.0.0.0/16",
    "compartment_id": "ocid1.compartment.oc1..example"
  }
}
__model_fqn - Fully-qualified class name: 
{
  "create_vcn_details": {
    "__model_fqn": "oci.core.models.CreateVcnDetails",
    "cidr_block": "10.0.0.0/16",
    "compartment_id": "ocid1.compartment.oc1..example"
  }
}

​
Nested Model Construction

Nested dictionaries and lists are recursively coerced to appropriate model types.

​
Authentication and Configuration

The server uses the same configuration as the OCI CLI:
  • Loads configuration from ~/.oci/config (or the profile specified by OCI_CONFIG_PROFILE)
  • Adds an additional user-agent suffix for MCP telemetry
  • Prefers Security Token Signer when security_token_file is available
  • Falls back to API key signer otherwise
oci setup config

​
Required Permissions

Permissions depend on the specific SDK operations being invoked. Use least-privilege IAM policies: Example: 
Allow group Developers to manage instances in compartment MyCompartment
Allow group Developers to use virtual-network-family in compartment MyCompartment
Security and PrivacyAll actions are performed with the permissions of the configured OCI profile. Follow best practices:
  • Use least-privilege IAM policies
  • Manage credentials securely
  • Avoid logging sensitive data
  • Be mindful of network egress and data residency
  • Review operations before execution

​
Common Use Cases

​
Service Exploration

  • Discover available operations for any service
  • Experiment with SDK functionality
  • Prototype integrations
  • Learn SDK capabilities

​
Flexible Automation

  • Access services without dedicated MCP servers
  • Build custom workflows
  • Integrate multiple services
  • Prototype before building specialized tools

​
Advanced Operations

  • Perform operations not covered by specialized servers
  • Access new SDK features immediately
  • Use preview/beta services
  • Execute complex multi-service workflows

​
Development & Testing

  • Test SDK calls interactively
  • Validate parameter formats
  • Debug API interactions
  • Build SDK knowledge

​
Best Practices

​
Client Selection

  • Use correct fully-qualified client name
  • Verify client exists in OCI SDK
  • Check SDK documentation for operations

​
Parameter Construction

  • Follow SDK parameter naming conventions
  • Use snake_case for parameter names
  • Provide all required parameters
  • Include optional parameters as needed

​
Error Handling

  • Check SDK documentation for exceptions
  • Validate OCIDs and formats
  • Handle pagination for list operations
  • Review error messages carefully

​
Performance

  • Be aware that the server auto-paginates list operations
  • Use appropriate filtering parameters
  • Limit result sets when possible
  • Cache results if making repeated calls

​
Troubleshooting

​
Client Not Found

Error: No module named ‘oci.xyz’
  • Verify client class name is correct
  • Check OCI SDK documentation
  • Ensure SDK version supports the service

​
Operation Not Found

Error: Client has no attribute ‘xyz’
  • Use list_client_operations to see available operations
  • Check spelling and case
  • Verify operation exists for that client

​
Invalid Parameters

Error: Missing required parameter / Invalid value
  • Check SDK documentation for required parameters
  • Verify parameter names match SDK expectations
  • Ensure OCIDs are valid
  • Check data types (string vs int, etc.)

​
Model Construction Fails

Error: Cannot construct model
  • Provide explicit __model or __model_fqn
  • Check model class exists
  • Verify all required model fields are provided
  • Review SDK model documentation

​
Permission Errors

Error: NotAuthorizedOrNotFound
  • Verify IAM policies grant required permissions
  • Check you’re using correct compartment
  • Ensure resource exists
  • Confirm authentication is valid

​
Advantages Over Specialized Servers

Flexibility
  • Access any OCI service immediately
  • No need to wait for specialized server updates
  • Experiment with new features
Completeness
  • Full SDK coverage
  • All operations available
  • No feature gaps
Direct SDK Access
  • No abstraction layer
  • Complete control over parameters
  • Access to all SDK capabilities

​
When to Use Specialized Servers

Consider using service-specific MCP servers when:
  • You need simpler, more intuitive interfaces
  • Operations are frequently performed
  • You want higher-level abstractions
  • Pre-built workflows are valuable
  • OCI API - CLI-based access
  • All specialized OCI servers - Service-specific tools

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us