> 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 (OCI)](https://docs.oracle.com/en-us/iaas/Content/generative-ai/mcp.htm?utm_source=chatgpt.com) can call CARTO's MCP Server through **MCP Calling** on the OpenAI-compatible **Responses API** using Streamable HTTP. MCP Calling is generally available (GA) on OCI Generative AI.

This is a **code-based integration** and requires an OCI administrator to configure the necessary IAM policies.

{% hint style="warning" %}
OCI Generative AI **Agents**, the service marketed as **Agent Factory**, cannot host **Agent Factory is not the MCP integration path.** OCI Generative AI **Agents**, the service marketed as **Agent Factory**, cannot host an MCP server and does not provide an MCP tool type. Its available tool types include RAG, SQL, function calling, HTTP endpoints, and agent tools.

CARTO MCP is connected through **OCI Generative AI's Responses API**, using MCP Calling.
{% endhint %}

## Authentication

**Oracle uses a token-based connection for MCP Calling.** OCI passes a pre-obtained bearer token to the MCP server and does not run an interactive OAuth flow\.As a result, the CARTO connection uses a **CARTO API Access Token**.

With the required token configuration, the integration provides access to the **read and discovery** subset of CARTO capabilities:

* Browsing connections
* Running SQL
* Searching the Data Observatory

For the broader set of CARTO tools, add the **SQL, Maps, and LDS APIs** to the token.

The following capabilities require OAuth and are therefore not available through this OCI integration:

* Starting a Workflow run
* Map authoring
* Workflow authoring
* Administrative operations

## Requirements

Before you start, you need:

* A tenancy in a region that supports agentic features. In EMEA, supported regions include **Frankfurt, London, and Riyadh**.
* An **OCI administrator** who can create the required IAM policy.
* A developer comfortable with **Python**.
* Your CARTO **MCP Server URL**.
* A CARTO **API Access Token** with the **MCP Server** scope.

## Install

### 1. Configure the IAM policy

An OCI administrator must grant your group permission to use the Generative AI service.

The `generative-ai-family` aggregate resource covers both inference and API-key operations.

Run the following as an administrator:

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

See [Oracle's IAM policy documentation](https://docs.oracle.com/en-us/iaas/Content/Identity/Concepts/policyoverview.htm) for more information.

### 2. Point the OpenAI SDK at Oracle

OCI Generative AI provides an OpenAI-compatible API, so you can use the OpenAI Python SDK by pointing the client at the OCI endpoint:

```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>",
)
```

Replace `<region>` and `<your-project-OCID>` with your OCI values.

See [Oracle's OpenAI compatibility documentation](https://docs.oracle.com/en-us/iaas/Content/generative-ai/developer-tutorials/using-openai-compatible-apis.htm) for more information.

### 3. Declare CARTO as an MCP tool

Pass the CARTO MCP Server as an MCP tool in the Responses API request:

```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"],
    }],
)
```

See [Oracle's MCP Calling documentation](https://docs.oracle.com/en-us/iaas/Content/generative-ai/mcp.htm?utm_source=chatgpt.com) for the complete MCP configuration and Responses API syntax.

{% 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.