Skip to main content
The OCI Identity MCP server provides tools to interact with Oracle Cloud Infrastructure Identity and Access Management (IAM) services, including compartment management, user operations, and tenancy information.

​
Installation

uvx oracle.oci-identity-mcp-server

​
Running the Server

​
STDIO Transport Mode

uvx oracle.oci-identity-mcp-server

​
HTTP Streaming Transport Mode

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

​
Environment Variables

  • OCI_CONFIG_PROFILE - OCI configuration profile name (default: “DEFAULT”)
  • TENANCY_ID_OVERRIDE - Overrides the tenancy ID from the config file

​
Available Tools

The server provides the following tools for identity management:
Tool NameDescription
list_compartmentsList compartments in a given tenancy
get_compartment_by_nameReturn a compartment matching the provided name
get_tenancy_infoGet tenancy information
get_current_tenancyGet current tenancy information
list_availability_domainsList availability domains in a given tenancy
list_subscribed_regionsReturn a list of all regions the customer (tenancy) is subscribed to
create_auth_tokenCreate an authentication token for a user
get_current_userGet current user information

​
Usage Examples

​
Compartment Management

List all compartments in my tenancy
Retrieves all compartments in the tenancy hierarchy, showing names, OCIDs, and states. 
Find the compartment named "Production"
Searches for a compartment by name and returns its details including OCID and description.

​
Tenancy Information

What is my current tenancy?
Retrieves information about the current tenancy including name, home region, and tenancy OCID. 
Get tenancy details
Shows comprehensive tenancy information useful for configuration and troubleshooting.

​
Availability Domains

List all availability domains
Returns all availability domains (ADs) in the current region, essential for resource placement.

​
Region Management

Show all regions I'm subscribed to
Lists all OCI regions where the tenancy is subscribed, including region names and keys.

​
User Operations

Who am I?
Retrieves information about the currently authenticated user. 
Create an auth token for user ocid1.user.oc1..example
Generates a new authentication token for API access or object storage operations.

​
Understanding OCI Identity

​
Compartments

Compartments are logical containers for organizing and isolating cloud resources:
  • Hierarchical Structure - Organize resources in a tree structure
  • Access Control - Apply IAM policies at compartment level
  • Cost Tracking - Track costs by compartment
  • Resource Isolation - Separate dev, test, and production environments
Best Practices:
  • Create compartments for different environments (dev, test, prod)
  • Use compartments for different projects or teams
  • Implement least-privilege access per compartment
  • Don’t put all resources in root compartment

​
Tenancy

The tenancy is the root compartment representing your organization:
  • Unique across all of OCI
  • Contains all compartments and resources
  • Has a home region that cannot be changed
  • Identified by tenancy OCID

​
Availability Domains

Availability Domains are isolated data centers within a region:
  • Physical isolation for fault tolerance
  • Independent power, cooling, and networking
  • Distribute resources across ADs for high availability
  • Some services are AD-specific, others are regional

​
Regions

OCI is available in multiple geographic regions:
  • Home Region - Where IAM resources are defined
  • Subscribed Regions - Regions you can deploy resources in
  • Region keys (e.g., us-phoenix-1, us-ashburn-1)
  • Some resources are region-specific

​
Authentication Tokens

Auth tokens are Oracle-generated tokens for API authentication:
  • Alternative to API signing keys
  • Used with object storage and other services
  • Can have multiple tokens per user
  • Should be rotated regularly

​
Authentication

The server uses OCI CLI configuration from ~/.oci/config: 
oci setup config

​
Required Permissions

Your OCI user or instance principal needs these IAM permissions: Compartment Management: 
Allow group IdentityAdmins to manage compartments in tenancy
Allow group IdentityAdmins to inspect compartments in tenancy
User Management: 
Allow group IdentityAdmins to manage users in tenancy
Allow group IdentityAdmins to manage auth-tokens in tenancy
Read-Only Access: 
Allow group IdentityReaders to inspect compartments in tenancy
Allow group IdentityReaders to inspect users in tenancy
Allow group IdentityReaders to read tenancies in tenancy
Self-Service (for own user): 
Allow group AllUsers to manage auth-tokens in tenancy where target.user.id = request.user.id
Security NoticeAll actions are performed with the permissions of the configured OCI CLI profile. We advise:
  • Least-privilege IAM setup
  • Secure credential management
  • Protect auth tokens like passwords
  • Rotate tokens regularly
  • Never expose tokens in logs or responses

​
Common Use Cases

​
Resource Organization

  • List compartments to understand resource hierarchy
  • Find compartment OCIDs for resource provisioning
  • Organize resources by environment or project
  • Implement cost tracking by compartment

​
Multi-Region Deployments

  • List subscribed regions for deployment planning
  • Understand region availability
  • Plan disaster recovery across regions
  • Distribute workloads geographically

​
High Availability Planning

  • List availability domains for resource distribution
  • Plan fault-tolerant architectures
  • Understand AD-specific services
  • Implement multi-AD deployments

​
Access Management

  • Create auth tokens for API access
  • Generate tokens for object storage
  • Manage user authentication methods
  • Implement programmatic access

​
Governance & Compliance

  • Audit compartment structure
  • Verify tenancy configuration
  • Track user access
  • Document resource organization

​
Architecture Patterns

​
Environment Separation

Root Compartment (Tenancy)
├── Development
│   ├── Network
│   ├── Compute
│   └── Database
├── Testing
│   ├── Network
│   ├── Compute
│   └── Database
└── Production
    ├── Network
    ├── Compute
    └── Database

​
Project-Based Organization

Root Compartment (Tenancy)
├── Project-A
│   ├── Dev
│   ├── Test
│   └── Prod
├── Project-B
│   ├── Dev
│   ├── Test
│   └── Prod
└── Shared-Services
    ├── Network
    └── Security

​
Troubleshooting

​
Authentication Errors

Error: NotAuthenticated
  • Verify OCI CLI configuration
  • Check API key validity
  • Ensure correct profile is selected
Error: InvalidParameter - tenancy
  • Verify TENANCY_ID_OVERRIDE if used
  • Check OCI config file has correct tenancy OCID

​
Permission Denied

Error: NotAuthorizedOrNotFound
  • Verify IAM policies grant required permissions
  • Check policy statements include correct compartments
  • Ensure using principal with appropriate access

​
Compartment Not Found

  • Verify compartment name spelling (case-sensitive)
  • Check compartment exists in current tenancy
  • Ensure compartment is not deleted
  • Use exact name match

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us