> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-agents/connect-your-platform/oracle.md).

# Oracle (OCI Generative AI)

Oracle Cloud Infrastructure can call CARTO's MCP Server through **MCP Calling** on the OpenAI-compatible **Responses API** (Streamable HTTP), which is GA on OCI Generative AI. This is a code-based integration and requires an OCI admin to write IAM policies.

{% hint style="warning" %}
**"Agent Factory" cannot host an MCP server.** OCI Generative AI **Agents** (the service marketed as Agent Factory) has no MCP tool type — its tool options are RAG, SQL, function calling, HTTP endpoint, and agent tools. MCP Calling lives on the separate **OCI Generative AI (inference)** service via the Responses API, which is the path documented here.
{% endhint %}

{% hint style="warning" %}
**Oracle is token-only.** OCI passes a pre-obtained bearer token and doesn't run an interactive OAuth flow, so CARTO's connection here uses an [API Access Token](/carto-for-agents/mcp-server/connecting-with-api-tokens.md) and reaches the [**read-and-discovery subset**](/carto-for-agents/mcp-server/connecting-with-api-tokens.md#what-a-token-unlocks) — browsing connections, running SQL, and searching the Data Observatory (with the SQL, Maps, and LDS APIs added to the token for the fuller set). Starting a Workflow run, map and workflow authoring, and admin need OAuth, which OCI can't provide.
{% endhint %}

## Requirements

* A tenancy in a region that supports agentic features (in EMEA: Frankfurt, London, Riyadh).
* An **OCI administrator** to write an IAM policy.
* A developer comfortable with Python.
* Your CARTO **MCP Server URL** and an **API Access Token** with the **MCP Server** scope.

## Install

**1. IAM policy** (run by an admin) — let your group use the Generative AI service (the `generative-ai-family` aggregate resource covers both inference and API-key operations):

```
allow group <your-group> to manage generative-ai-family in compartment <compartment>
```

**2. Point the OpenAI SDK at Oracle**

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://inference.generativeai.<region>.oci.oraclecloud.com/openai/v1",
    api_key="<your-genai-api-key>",
    project="<your-project-OCID>",
)
```

**3. Declare CARTO as an MCP tool**

```python
resp = client.responses.create(
    model="<model>",
    input="What CARTO connections do I have?",
    tools=[{
        "type": "mcp",
        "server_label": "carto",
        "server_url": "https://<region>.api.carto.com/mcp/<account_id>",
        "authorization": "<CARTO API token — raw, without the 'Bearer ' prefix>",
        "require_approval": "never",
        "allowed_tools": ["explore_data", "search_data_observatory"],
    }],
)
```

{% hint style="info" %}
Two details: the token goes in `authorization` **without** the `Bearer` prefix (OCI adds it), and `require_approval` controls whether the agent pauses before running a tool — set it deliberately. Use `allowed_tools` to expose a focused, low-risk set and to suppress `view_map` (which can't render inline here).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.carto.com/carto-for-agents/connect-your-platform/oracle.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.