Skip to main content
The OCI Compute Instance Agent MCP server provides tools for interacting with the Oracle Cloud Infrastructure Compute Instance Agent service. This enables remote command execution and management on compute instances.

​
Installation

uvx oracle.oci-compute-instance-agent-mcp-server

​
Running the Server

​
STDIO Transport Mode

uvx oracle.oci-compute-instance-agent-mcp-server

​
HTTP Streaming Transport Mode

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

​
Available Tools

The server provides the following tools for managing instance agent commands:
Tool NameDescription
list_instance_agent_commandsList all instance agent commands
get_instance_agent_commandGet detailed information about a specific command by ID
create_instance_agent_commandCreate and execute a new instance agent command
list_instance_agent_command_executionsList command executions for an instance agent command

​
Usage Examples

​
List Instance Agent Commands

List all instance agent commands in my compartment
Retrieves all commands that have been executed or scheduled through the instance agent.

​
Create and Execute a Command

Run the command "df -h" on instance ocid1.instance.oc1.phx.example
Creates a new instance agent command to execute on the specified instance. The Instance Agent must be running on the target instance.

​
Get Command Details

Show me details for command ocid1.instanceagentcommand.oc1.phx.example
Retrieves comprehensive information about a specific command including its status, output, and execution details.

​
Check Command Execution Status

List all executions for command ocid1.instanceagentcommand.oc1.phx.example
Shows the execution history and status for a command, useful for tracking progress and troubleshooting.

​
Understanding Instance Agent Commands

The Instance Agent is a lightweight process that runs on compute instances and enables:
  • Remote Command Execution - Run shell commands without SSH access
  • Automated Scripts - Execute maintenance and configuration scripts
  • Monitoring & Diagnostics - Collect system information remotely
  • Patch Management - Apply updates and patches programmatically

​
Command Types

Supported command types include:
  • Shell commands (bash, sh)
  • PowerShell scripts (Windows instances)
  • Custom scripts with arguments

​
Command Lifecycle

  1. Created - Command is defined and submitted
  2. Accepted - Instance agent receives the command
  3. In Progress - Command is executing
  4. Succeeded - Command completed successfully
  5. Failed - Command encountered an error
  6. Canceled - Command was canceled before completion

​
Authentication

The server uses OCI CLI configuration from ~/.oci/config. Ensure you have:
  1. OCI CLI installed and configured
  2. Valid API credentials
  3. Appropriate IAM permissions for instance agent operations
oci setup config

​
Required Permissions

Your OCI user or instance principal needs these IAM permissions: 
Allow group InstanceAgentAdmins to manage instance-agent-commands in compartment MyCompartment
Allow group InstanceAgentAdmins to read instances in compartment MyCompartment
For read-only access: 
Allow group InstanceAgentViewers to inspect instance-agent-commands in compartment MyCompartment

​
Instance Agent Requirements

For commands to execute successfully:
  1. Instance Agent Must Be Running - The agent is pre-installed on Oracle-provided images
  2. Network Connectivity - Instance needs internet access to reach OCI services
  3. Service Enablement - Instance agent plugin must be enabled

​
Verify Instance Agent Status

You can check if the instance agent is running through the OCI Console or CLI: 
oci compute instance-agent get --instance-id <instance-ocid>
Security ConsiderationsInstance agent commands execute with elevated privileges. Always:
  • Validate command inputs
  • Use least-privilege principles
  • Audit command execution
  • Avoid passing secrets in commands
  • Review command outputs for sensitive data

​
Common Use Cases

​
System Administration

  • Check disk space and system resources
  • Restart services and applications
  • Clear caches and temporary files
  • Update configuration files

​
Monitoring & Diagnostics

  • Collect system logs
  • Check process status
  • Gather performance metrics
  • Run diagnostic scripts

​
Automation

  • Deploy application updates
  • Execute maintenance scripts
  • Configure system settings
  • Manage users and permissions

​
Compliance & Security

  • Run security scans
  • Verify compliance configurations
  • Collect audit information
  • Update security patches

​
Example Commands

​
Check Disk Usage

Create a command to run "df -h" on instance ocid1.instance.oc1.phx.example

​
List Running Processes

Execute "ps aux" on instance ocid1.instance.oc1.phx.example

​
Restart a Service

Run "sudo systemctl restart httpd" on instance ocid1.instance.oc1.phx.example

​
Collect Logs

Execute "tail -n 100 /var/log/messages" on instance ocid1.instance.oc1.phx.example

​
Troubleshooting

​
Command Not Executing

Possible causes:
  • Instance agent is not running
  • Instance lacks internet connectivity
  • Insufficient permissions
  • Invalid command syntax
Solutions:
  1. Verify instance agent status in OCI Console
  2. Check instance internet gateway and NAT gateway configuration
  3. Review IAM policies
  4. Test command syntax manually via SSH

​
Command Timed Out

Long-running commands may timeout. Consider:
  • Breaking commands into smaller steps
  • Running commands asynchronously
  • Increasing timeout values if supported

​
Permission Denied Errors

Commands run as the oracle-cloud-agent user. For privileged operations:
  • Use sudo in your commands
  • Ensure sudo is properly configured
  • Check file and directory permissions

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us