> 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.