OCI Resource Search MCP Server

​

Installation

uvx oracle.oci-resource-search-mcp-server

​

Running the Server

​

STDIO Transport Mode

uvx oracle.oci-resource-search-mcp-server

​

HTTP Streaming Transport Mode

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

​

Available Tools

​

Usage Examples

​

Search All Resources

Search for all resources in my tenancy

​

Search by Resource Type

Find all compute instances

List all VCNs in my tenancy

​

Search by Compartment

Find all resources in compartment "Production"

​

Search by Name

Find resources named "web-server"

​

Search by Tag

Find all resources tagged with Environment=Production

​

Complex Queries

Find all running compute instances in the Production compartment

​

Understanding Resource Search

​

What is Resource Search?

• Cross-Service Search - Find resources across all OCI services
• Cross-Compartment Search - Search entire tenancy or specific compartments
• Structured Queries - Use Resource Query Language (RQL)
• Tag-Based Discovery - Find resources by tags and metadata
• Real-Time Results - Query live resource inventory

​

Resource Query Language (RQL)

query <resourceType> resources [where <condition>]

-- Find all instances
query instance resources

-- Find instances by name
query instance resources where displayName = 'web-server'

-- Find running instances
query instance resources where lifecycleState = 'RUNNING'

-- Find resources by compartment
query all resources where compartmentId = 'ocid1.compartment...'

-- Find resources by tag
query all resources where (definedTags.namespace.key = 'value')

-- Complex queries
query instance resources where (lifecycleState = 'RUNNING' && compartmentId = 'ocid1...')

​

Searchable Resource Types

• Instance (compute instances)
• Image
• BootVolume
• Volume
• VolumeBackup
• BootVolumeBackup

• Vcn (Virtual Cloud Networks)
• Subnet
• SecurityList
• NetworkSecurityGroup
• InternetGateway
• NatGateway
• ServiceGateway
• RouteTable
• DRG (Dynamic Routing Gateway)

• AutonomousDatabase
• DbSystem
• Database
• DbHome

• LoadBalancer
• NetworkLoadBalancer

• Compartment
• User
• Group
• Policy

• Bucket

​

Search Attributes

• displayName - Resource name
• lifecycleState - Resource state (RUNNING, STOPPED, etc.)
• compartmentId - Compartment OCID
• timeCreated - Creation timestamp
• definedTags - Defined tag namespaces and keys
• freeformTags - Freeform tags
• identifier - Resource OCID
• Resource-specific attributes

​

Authentication

oci setup config

​

Required Permissions

Allow group SearchUsers to use search-resources in tenancy

Allow group SearchUsers to inspect all-resources in tenancy

​

Common Use Cases

​

Resource Inventory

• Catalog all resources in tenancy
• Count resources by type
• Identify resource distribution across compartments
• Track resource growth over time

​

Cost Management

• Find all resources with specific cost tags
• Identify untagged resources
• Locate resources for showback/chargeback
• Find resources for cost optimization

​

Compliance & Governance

• Verify tagging compliance
• Find resources missing required tags
• Audit resource configurations
• Identify non-compliant resources

​

Operations & Troubleshooting

• Locate resources by name
• Find resources in specific states
• Identify orphaned resources
• Discover dependencies

​

Migration & Cleanup

• Find all resources in old compartments
• Identify resources for migration
• Locate unused or idle resources
• Plan resource consolidation

​

Security Auditing

• Find public-facing resources
• Identify resources without encryption
• Locate resources with specific configurations
• Audit access patterns

​

Query Examples

​

Find Running Instances

Find all running compute instances

query instance resources where lifecycleState = 'RUNNING'

​

Find Resources by Tag

Find all resources tagged with Environment=Production

query all resources where (definedTags.namespace.Environment = 'Production')

​

Find Resources Created Recently

Find resources created in the last 7 days

query all resources where (timeCreated >= '2024-01-01T00:00:00Z')

​

Find Untagged Resources

Find all compute instances without tags

​

Find Resources in Specific Compartment

List all databases in the Production compartment

query database resources where compartmentId = 'ocid1.compartment...'

​

Best Practices

​

Effective Searching

• Use specific resource types when possible (faster results)
• Combine conditions to narrow results
• Use pagination for large result sets
• Cache frequent queries
• Leverage tags for better organization

​

Tagging Strategy

• Implement consistent tagging policies
• Use defined tags for controlled vocabularies
• Tag resources at creation
• Use tag defaults for automation
• Regular tag compliance audits

​

Performance

• Limit search scope to specific compartments when possible
• Use specific resource types instead of “all”
• Implement result caching for dashboards
• Avoid overly complex queries

​

Organization

• Document common search queries
• Create saved queries for frequent searches
• Share useful queries with team
• Build automation around searches

​

Advanced Patterns

​

Resource Dependency Mapping

1. Find VCN
2. Search for subnets in that VCN
3. Search for instances in those subnets
4. Map complete architecture

​

Cost Allocation

1. Search by cost center tag
2. Group resources by type
3. Calculate resource counts
4. Generate cost reports

​

Compliance Scanning

1. Search for resource type
2. Check required attributes
3. Identify non-compliant resources
4. Generate compliance report

​

Cleanup Automation

1. Search for idle resources
2. Check last activity
3. Identify candidates for deletion
4. Generate cleanup recommendations

​

Troubleshooting

​

No Results Returned

• No resources match query
• Insufficient permissions to view resources
• Incorrect query syntax
• Wrong compartment specified

1. Verify resources exist via console
2. Check IAM permissions
3. Validate query syntax
4. Try broader search criteria

​

Permission Denied

• Verify use search-resources permission
• Check read permissions on resource types
• Ensure searching in accessible compartments
• Validate tenancy access

​

Query Syntax Errors

• Check RQL syntax documentation
• Verify attribute names are correct
• Ensure proper quoting of values
• Test simple queries first

​

Incomplete Results

• Check pagination - may need to fetch additional pages
• Verify all compartments are searched
• Ensure resources are in expected state
• Confirm no permission gaps

​

Integration Ideas

​

CMDB Integration

• Export resource inventory
• Update configuration management database
• Track resource changes
• Maintain accurate asset records

​

Cost Reporting

• Search by cost tags
• Aggregate resource counts
• Generate cost allocation reports
• Track resource usage trends

​

Security Scanning

• Find resources with security issues
• Identify configuration gaps
• Generate security reports
• Automate remediation

​

Automation

• Scheduled resource audits
• Automated tagging compliance
• Resource lifecycle management
• Dynamic inventory for Ansible/Terraform

​

Related Services

• Identity - Manage compartments and access
• Monitoring - Monitor found resources
• Cloud Guard - Security scanning
• Compute - Manage found instances

​

Additional Resources

• OCI Resource Search Documentation
• Resource Query Language Reference
• OCI Python SDK - Resource Search