OCI Policy Analysis Part 3 – Bringing OCI Policy Intelligence to AI Agents with MCP

OCI Policy Analysis started with a straightforward goal: make it easier to understand Oracle Cloud Infrastructure IAM policies. The first version loaded policies, compartments, groups, dynamic groups, and user membership data, then presented that information in a way that could be searched and reviewed.

That remains useful, but the project has moved in a broader direction. The real value is not just in a desktop tab or a table. The value is in the parsed, augmented policy model underneath: a local representation of OCI IAM data that knows about policy statements, subjects, verbs, resources, conditions, effective compartments, identity domains, group membership, dynamic groups, resource principals, cross-tenancy aliases, and derived policy intelligence.

Model Context Protocol, or MCP, is a natural next step for that model.

MCP gives AI clients a standard way to call tools. For OCI Policy Analysis, that means an AI agent can ask structured questions against real tenancy data instead of relying on pasted policy text, screenshots, or generic IAM knowledge. The agent can parse a natural language question, choose the right MCP tool, provide a JSON query, receive structured results, and then organize the answer for the user.

The important point is that MCP does not replace the analysis engine. It merely exposes all of the capabilities in a way that an AI Agent can translate.

Why MCP Fits Policy Analysis

IAM policy analysis has two characteristics that make it a strong MCP use case.

First, the questions are often natural language questions:

Second, the answers require deterministic data processing. An AI model can help interpret intent and summarize results, but the underlying data retrieval should not be a guess. Policy analysis needs reliable filtering, identity resolution, condition parsing, historical comparison, and structured output.

That is where OCI Policy Analysis and MCP work well together. The AI agent handles the conversation, while MCP server handles the query and results generated using the tool’s cached data.

The Strategy: Collect, Parse, Enrich, Expose

The MCP implementation follows the same strategy as the rest of OCI Policy Analysis:

1. Collect the source data from OCI APIs or from a previously saved combined cache.
2. Normalize the data into a shared model of policies, compartments, identities, dynamic groups, cross-tenancy statements, and related metadata.
3. Parse the policy statements into structured fields such as subject, verb, resource, location, and conditions.
4. Augment the data with intelligence, including effective compartment scope, invalid statement detection, dynamic group usage, principal evidence, tag condition parsing, and workload identity context.
5. Expose focused tools that allow clients to search, compare, and reason over the enriched model.

That last step is where MCP becomes useful. Instead of giving an AI client a giant JSON file and asking it to figure everything out, the server exposes purpose-built tools with narrow responsibilities.

Examples include:

• policy_search for searching parsed IAM policy statements.
• policy_search_set for running multiple related searches and summarizing coverage.
• policy_history_search for comparing search results across two snapshots.
• identity_search for users, groups, dynamic groups, compartments, and membership lookups.
• tag_based_policy_search for parsed tag-condition analysis.
• oke_workload_identity_search for guided workload identity policy analysis.
• cross_tenancy_search for defined aliases and Admit/Endorse style policy review.
• data_operations for cache inspection, cache loading, status checks, and reload operations.

Each tool is intentionally more focused than a single tool that might “answer any OCI policy question.” This is a better because it gives the AI agent clear choices and gives the server room to return predictable, compact, structured results.

MCP Deployment Is Flexible

One of the best parts of MCP is that it does not force a single deployment model. OCI Policy Analysis supports multiple ways to run the server depending on where the data lives and how the client connects.

The simplest pattern is local STDIO. In this model, an MCP client such as Claude Desktop or OpenAI Codex starts the OCI Policy Analysis MCP server as a python or docker subprocess. The server loads a local cache or connects to OCI using a configured profile, then communicates with the client over standard input and output.

That pattern is convenient for individual use. If you have already loaded a tenancy in the desktop or web application, it saved a cache when it loaded, and you can point the MCP server to that cache and ask questions without making live OCI API calls.

A second pattern is streamable HTTP. In this model, the MCP server runs as a local or remote HTTP service. Clients connect to it over an MCP HTTP endpoint. This works well when the MCP server should stay running independently from the client, or when multiple tools need access to the same loaded data. 

Finally, OCI Policy Analysis also supports an embedded MCP server inside the desktop application. With that flow, you can load policy and IAM data in the UI, start the embedded MCP server from the MCP tab, and expose the same in-memory analysis state to MCP clients over HTTP.

For more durable deployments, the tool can run on OCI. For example, it can be packaged into a container image, pushed to OCIR, and deployed on OCI Container Instances in a private subnet. In that model, the server can use resource principal authentication, load tenancy data at startup, expose streamable HTTP on a private endpoint, and optionally sit behind an OCI Load Balancer (with tightened Security List or NSG) for controlled access.

Those options matter because policy data is sensitive. Some users will want everything local. Others will want a shared internal endpoint. Others will want cache-only analysis for offline review. MCP is flexible enough to support those patterns without changing the core tool’s capabilities.  And if required, this MCP server could be behind an MCP Gateway for added security and monitoring.

The next couple sections give some practical examples for quickly getting up to speed.

Example 1: Loading OCI Policy Analysis in Claude Desktop

For Claude Desktop, a common local pattern is STDIO with a cached data set.  These examples assume that the OCI Policy Analysis pre-requisites are already met – namely a Python Virtual Environment with the correct packages, and an OCI Profile that maps to a user/group given access to policy data – both of these are documented in the repository.

Example configuration:

{
  "mcpServers": {
    "oci-policy-local": {
      "command": "/path/to/oci-policy-analysis/.venv/bin/python",
      "args": [
        "-m",
        "oci_policy_analysis.mcp_server",
        "--use-cache",
        "mytenancy_2026-06-01-12-00-00-UTC"
      ],
      "env": {
        "MCP_STDIO_MODE": "1",
        "PYTHONUNBUFFERED": "1",
        "PYTHONWARNINGS": "ignore"
      },
      "type": "stdio"
    }
  }
}

The same pattern can load tenancy data through an OCI SDK profile into its internal cache:

{
  "mcpServers": {
    "oci-policy-live": {
      "command": "/path/to/oci-policy-analysis/.venv/bin/python",
      "args": [
        "-m", oci_policy_analysis.mcp_server",
        "--profile", DEFAULT"
      ],
      "env": {
        "MCP_STDIO_MODE": "1",
        "PYTHONUNBUFFERED": "1",
        "PYTHONWARNINGS": "ignore"
      },
      "type": "stdio"
    }
  }
}

For HTTP mode, Claude Desktop commonly uses an MCP proxy that points to a running MCP endpoint:

{
  "mcpServers": {
    "oci-policy-remote": {
      "command": "mcp-proxy",
      "args": [
        "https://oci-policy-analysis-mcp.example.com/mcp"
      ]
    }
  }
}

Note that there are several command line parameters available to control logging, identity domain search depth, and other aspects of data loading.  These are optional and documented.

Example 2: Loading OCI Policy Analysis in Codex or Other Agent Environments

Codex and other agent environments can consume MCP tools when they are configured with a server command or an HTTP MCP endpoint. The exact configuration file and UI can vary by client, but the OCI Policy Analysis side is the same.

For local STDIO, the important pieces are:

command: /path/to/oci-policy-analysis/.venv/bin/python
args: -m oci_policy_analysis.mcp_server --use-cache <cache-name> | --profile <your OCI Profile>
env: MCP_STDIO_MODE=1, PYTHONUNBUFFERED=1, PYTHONWARNINGS="ignore"
transport: stdio

For HTTP, the important pieces are:

url: http://127.0.0.1:8765/mcp
transport: http

Or, for a remote private deployment:

url: https://oci-policy-analysis-mcp.example.com/mcp
transport: http

Once connected, the agent sees the tool list and schemas. From there, a user can ask natural language questions and let the agent decide when to call identity_search, policy_search, policy_search_set, or another focused tool.

What the Agent and MCP Server Actually Do

Consider the question:

Which policies allow the Default Administrators group to manipulate resources?

An agent should not simply search pasted text. It can call policy_search with a structured principal filter – one that the end user didn’t know they could use. In this case, we search for all policies granting verbs manage or use to the Default Administrator:

{
  "mode": "simple",
  "detail_level": "simple",
  "filters": {
    "principal": {
      "principal_type": "group",
      "domain_name": "Default",
      "name": "Administrators"
    },
    "verb": ["manage", "use"]
  },
  "limit": 50
}

The tool can match statements that reference the group by name and, when identity data supports it, equivalent statements that reference the group by OCID. The agent can then summarize the policies, compartments, resources, and any notable conditions.

For a more specific question:

What database management or object storage access exists in production?

The agent might use (Again, the MCP policy_search tool ):

{
  "mode": "simple",
  "detail_level": "summary",
  "filters": {
    "verb": ["manage", "use", "read"],
    "resource": ["database-family", "databases", "object", "bucket"],
    "effective_path": ["ROOT/Production"]
  },
  "limit": 25
}

The server returns counts, breakdowns, and sample matching statements. The agent turns those results into an answer a human can read. Note that effective path is more than just a compartment – it is calculated internally after parsing, so that we understand where in the hierarchy a policy statement takes effect, not just where it sits.

For identity exploration:

Show me the users in the Federated domain’s Administrators group.

The agent can call the identity_search tool with:

{
  "operation": "members_for_group",
  "entity_types": ["user"],
  "domain_name": ["Federated"],
  "name": ["Administrators"],
  "limit": 50
}

For historical comparison:

Compare policies pertaining to administrative access between the current cache and last weeks’s cache.

The agent can use policy_history_search with a policy query and two snapshot selectors. The useful part is that the diff happens against structured statement identity, not just a text blob.

{
   "left": {
     "source": "as_of",
     "as_of": "2026-06-18T00:00:00Z"
   },
   "right": {
      "source": "current"
   },
   "query_type": "single",
   "diff_mode": "statement_identity",
   "query": {
      "mode": "advanced",
      "detail_level": "summary",
      "limit": 100,
      "filters": {
        "verb": ["use", "manage"]
      }
   }
}

For install validation or product readiness:

Check whether all required policies exist for this service.

The agent can use policy_search_set, where each search represents one required policy component: human administrator access, service principal access, workload access, dynamic group access, or compartment-specific permissions. The response can identify missing required searches and ambiguous results. The actual query here is omitted, but the point is made – often multiple statements involving different types of principals, differing access, and locations across a tenancy may be needed to enable services.

This is where MCP becomes more than a query interface. It lets the user ask the question naturally while the agent maps the request to the correct tool sequence.

Why Parsing and Intelligence Matter

The key to making this work is the parsing layer.

OCI policies are readable, but many real questions depend on information that is not obvious from a single policy statement. For example:

• A policy can be written at one compartment but apply to another effective scope.
• A group might be referenced by name in one statement and OCID in another.
• A dynamic group can be defined but unused.
• An any-user policy can actually be constrained to a resource principal through multiple request.principal.* conditions.
• A workload identity policy may depend on namespace, service account, cluster, and residual conditions.
• Tag-based policy conditions can contain access semantics that should be parsed instead of treated as plain text.
• Cross-tenancy policies may depend on aliases that need to be resolved together.

If the MCP server only returned raw statements, the AI agent would have to infer too much. By parsing and enriching the data before exposing it, OCI Policy Analysis lets the agent ask better queries and provide better summaries.

This is also why the MCP tool schemas are intentionally compact. Large schemas consume context and make tool selection harder. The server keeps tool descriptions concise, then provides structured fields and response breakdowns that are useful after the call.

Practical Guardrails

There are a few practical points worth emphasizing.

Use cached data when you want repeatable offline analysis. Cache-based MCP startup is fast and avoids live API calls.

Use live loading when freshness matters. The MCP server can load through an OCI profile, instance principal, resource principal, or session-token style flow depending on how it is deployed.

Use HTTP mode when the server should be long-running or shared. Use STDIO when the MCP client should own the server lifecycle.

Use lower detail levels for broad questions. Summary responses are better for wide searches, while full detail is better for targeted investigations.

Use logging while tuning prompts and client behavior. Starting the server with an INFO log level records tool inputs and truncated outputs, which helps validate how an agent is translating natural language into real tool calls.

Most importantly, treat the MCP server as an access path to sensitive IAM data. Run it where the data is allowed to be queried, use appropriate network controls, and avoid exposing it broadly.

Where This Is Going

For me, MCP is the bridge between a useful standalone analysis tool and a more interactive policy intelligence workflow. The goal is not for an AI agent to “know” a tenancy. The goal is for the agent to use real tools against real parsed data, then help the user understand what it found.

That opens up practical workflows:

• Ask policy questions without learning every filter field.
• Compare current and historical access.
• Build reusable policy validation checks.
• Investigate dynamic groups, workload identities, and tag-based access.
• Summarize broad policy exposure in language that an operator, architect, or security reviewer can act on.

OCI Policy Analysis will continue to evolve in this direction. The tool surface can expand as new analysis use cases are identified, while the underlying strategy remains the same: collect the right data, parse it carefully, enrich it with useful intelligence, and expose it through focused interfaces.

For more official Oracle MCP examples, see the Oracle MCP GitHub repository: https://github.com/oracle/mcp. I plan to contribute OCI Policy Analysis there soon, so that these patterns can be easier to discover and reuse alongside other Oracle MCP examples.

All of the (evolving) documentation for OCI Policy Analysis itself is located here: https://agregory999.github.io/oci-policy-analysis/

Previous posts from the OCI Policy Analysis series are here:

Part 1: https://blogs.oracle.com/cloud-infrastructure/oci-policy-analysis-tool-part1-overview

Part 2: https://blogs.oracle.com/cloud-infrastructure/oci-policy-analysis-part-2-strategy