> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nimbleway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Oracle OCI

> Get started with Nimble on Oracle Cloud Infrastructure: deploy the Managed Enterprise Chat Agent with Nimble web search, or connect Nimble MCP to OCI Generative AI.

Give agents on Oracle Cloud Infrastructure (OCI) live web data from Nimble. There are two ways in, and both use the same Nimble API key.

| Path | Best for | What you configure |
| - | - | - |
| [Managed Enterprise Chat Agent](#deploy-the-managed-enterprise-chat-agent) | A ready-made RAG chat app on OCI, with web search built in | Your Nimble API key in the Resource Manager form, plus network settings |
| [Nimble MCP with OCI Generative AI](#connect-nimble-mcp-to-oci-generative-ai) | Your own agent code calling models hosted on OCI | One `mcp` tool in a Responses API request |

## Prerequisites

* A Nimble API key from the [Nimble dashboard](https://online.nimbleway.com/settings/api-keys). A free trial is available.
* An OCI tenancy.
* For the chat agent: `git`, `python3`, and `zip` on your machine, and rights to create IAM policies in the tenancy. See [Fill in the pack settings](#deploy-the-managed-enterprise-chat-agent) if you lack them.
* For MCP: an OCI Generative AI project, an OCI Generative AI API key, and an IAM policy that grants the key access. The [setup step](#how-it-works) links Oracle's guide.

## Deploy the Managed Enterprise Chat Agent

The [OCI AI Accelerator Starter Packs](https://github.com/oci-ai-incubations/ai-accelerator-starter-packs) are Terraform stacks from Oracle. They deploy complete AI apps onto Oracle Kubernetes Engine (OKE). The **Managed Enterprise Chat Agent** pack (`paas_rag`) is an enterprise chat app. It answers questions over your uploaded documents with citations, using OCI Generative AI models and Oracle 26ai as the vector store. It needs no GPUs.

Nimble is the pack's built-in web search provider. Add your Nimble API key at deploy time and the pack's backend answers web search requests with Nimble.

<Warning>
  The Nimble setting was added after Oracle's latest published release. The `v0.0.8_paas_rag.zip` on the Releases page does not include it. Build the stack zip from the repository's `main` branch, as shown below, until a newer release ships.
</Warning>

<Steps>
  <Step title="Build the stack zip">
    Clone the repository, generate the schema for the `paas_rag` pack, and zip the Terraform folder:

    ```bash theme={"system"}
    git clone https://github.com/oci-ai-incubations/ai-accelerator-starter-packs.git
    cd ai-accelerator-starter-packs
    python3 -m venv venv && source venv/bin/activate
    pip3 install -r requirements.txt
    python3 create_final_schema.py -c paas_rag
    zip -r paas_rag.zip ai-accelerator-tf
    ```
  </Step>

  <Step title="Create the stack in OCI Resource Manager">
    In the OCI Console, go to **Developer Services → Resource Manager → Stacks**. Pick your compartment, click **Create Stack**, select **.zip file**, and upload `paas_rag.zip`. Click **Next**.
  </Step>

  <Step title="Fill in the pack settings">
    The form groups settings by section. These are the ones that matter for this pack:

    | Section | Setting | What to enter |
    | - | - | - |
    | Deployment Configuration | **RAG Deployment Size** | `small` to start. `medium` provisions a larger database (16 ECPU, 8 TB). |
    | Deployment Configuration | **OCI GenAI Services Region** | A region where OCI Generative AI is available. It does not have to match the cluster region. Default: `us-chicago-1`. |
    | OCI Blueprints Administrator Account | Username, password, email | The login for the OCI AI Blueprints portal, which manages the deployment. The chat app itself has no login. |
    | Oracle 26ai Database | **Database Admin Password** | 12+ characters, with uppercase, lowercase, a number, and one of `!@#$%^&*`. |
    | Web Search | **Nimbleway API Key** | Your Nimble API key. |

    The **Nimbleway API Key** field is optional. Leave it blank and web search is unavailable.

    **Create IAM Policies**, under **Advanced Options**, is on by default and writes policies at the tenancy root. That needs tenancy-admin rights. Without them, uncheck it and have an admin apply [Oracle's IAM policies](https://github.com/oci-ai-incubations/ai-accelerator-starter-packs/blob/main/docs/iam-policies.md) first.

    <Warning>
      By default the stack deploys a public URL, and the API behind it requires no login. Anyone with the URL can run web searches on your Nimble key, use your OCI Generative AI quota, and read uploaded documents. For anything beyond a short test, check **Deploy Private K8s and Load Balancer** under **Advanced Options**, or [restrict ingress by IP](https://github.com/oci-ai-incubations/ai-accelerator-starter-packs/blob/main/docs/limiting_ips_for_public_ingress.md).
    </Warning>
  </Step>

  <Step title="Apply the stack">
    Click **Next → Run apply → Create**. Deployment takes roughly 20 to 40 minutes. When it finishes, the stack's **Outputs** tab shows the chat app's address as **RAG Service URL**.

    To stop all charges later, open the stack and click **Destroy**.
  </Step>
</Steps>

### What the Nimble setting does

The pack runs [OGX](/integrations/connectors/ogx), the open agentic API server, as its backend. Your API key is passed to OGX's `remote::nimble-search` provider, which is the pack's only web search backend. Any `web_search` tool call the backend handles goes to Nimble [Search](/nimble-sdk/web-tools/search).

The stack ships with this provider configuration:

```yaml theme={"system"}
tool_runtime:
  - provider_id: nimble-search
    provider_type: remote::nimble-search
    config:
      api_key: ${env.NIMBLEWAY_API_KEY:=}
      max_results: 3
      search_depth: lite
```

`max_results: 3` and `search_depth: lite` keep searches fast by default: titles, URLs, and snippets for the top three results. To change them, edit `ai-accelerator-tf/files/llamastack_paas_config.yaml` before you build the zip. See the [OGX page](/integrations/connectors/ogx#configuration) for every option.

<Note>
  Terraform users can set the key as the `nimbleway_api_key` variable instead of using the console form. It is marked sensitive, so Terraform does not print it.
</Note>

## Connect Nimble MCP to OCI Generative AI

OCI Generative AI serves an OpenAI-compatible Responses API. It supports [MCP calling](https://docs.oracle.com/en-us/iaas/Content/generative-ai/mcp.htm): OCI connects to a remote MCP server directly, with no tool-calling loop in your code. Point it at Nimble's hosted MCP server and OCI models that support the Responses API can search and extract the web.

Set three environment variables before you run the example:

```bash theme={"system"}
export OCI_GENAI_API_KEY="your-oci-genai-api-key"
export OCI_GENAI_PROJECT_OCID="ocid1.generativeaiproject.oc1.us-chicago-1.xxxx"
export NIMBLE_API_KEY="your-nimble-api-key"
```

### Example Request

<CodeGroup>
  ```python Python theme={"system"}
  import os
  from openai import OpenAI

  client = OpenAI(
      base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",
      api_key=os.environ["OCI_GENAI_API_KEY"],
      project=os.environ["OCI_GENAI_PROJECT_OCID"],
  )

  response = client.responses.create(
      model="openai.gpt-oss-120b",
      tools=[
          {
              "type": "mcp",
              "server_label": "nimble",
              "server_description": "Live web search and page extraction.",
              "server_url": "https://mcp.nimbleway.com/mcp",
              "authorization": os.environ["NIMBLE_API_KEY"],
              "allowed_tools": ["nimble_search", "nimble_extract"],
              "require_approval": "never",
          }
      ],
      input="What did Oracle announce this week? Search the web and cite sources.",
  )

  print(response.output_text)
  ```

  ```typescript TypeScript theme={"system"}
  import OpenAI from "openai";

  // Fail fast: an unset key would make the SDK fall back to OPENAI_API_KEY.
  function env(name: string): string {
    const value = process.env[name];
    if (!value) throw new Error(`Set ${name} first`);
    return value;
  }

  const client = new OpenAI({
    baseURL: "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",
    apiKey: env("OCI_GENAI_API_KEY"),
    project: env("OCI_GENAI_PROJECT_OCID"),
  });

  const response = await client.responses.create({
    model: "openai.gpt-oss-120b",
    tools: [
      {
        type: "mcp",
        server_label: "nimble",
        server_description: "Live web search and page extraction.",
        server_url: "https://mcp.nimbleway.com/mcp",
        authorization: env("NIMBLE_API_KEY"),
        allowed_tools: ["nimble_search", "nimble_extract"],
        require_approval: "never",
      },
    ],
    input: "What did Oracle announce this week? Search the web and cite sources.",
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={"system"}
  curl https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1/responses \
    -H "Authorization: Bearer $OCI_GENAI_API_KEY" \
    -H "OpenAI-Project: $OCI_GENAI_PROJECT_OCID" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai.gpt-oss-120b",
      "tools": [{
        "type": "mcp",
        "server_label": "nimble",
        "server_description": "Live web search and page extraction.",
        "server_url": "https://mcp.nimbleway.com/mcp",
        "authorization": "'"$NIMBLE_API_KEY"'",
        "allowed_tools": ["nimble_search", "nimble_extract"],
        "require_approval": "never"
      }],
      "input": "What did Oracle announce this week? Search the web and cite sources."
    }'
  ```
</CodeGroup>

Any OpenAI-compatible client works the same way. The TypeScript example uses top-level `await`, so run it as an ES module.

### How it works

<Steps>
  <Step title="Set up OCI Generative AI">
    In the OCI Console, create a Generative AI **project** and an **API key** in the same region. Grant the key permission with an IAM policy. Oracle's [quick start](https://docs.oracle.com/en-us/iaas/Content/generative-ai/get-started-agents.htm) walks through all three.
  </Step>

  <Step title="Add Nimble as an mcp tool">
    Set `server_url` to `https://mcp.nimbleway.com/mcp` and put your Nimble API key in `authorization`. Pass the raw key, with no `Bearer` prefix.
  </Step>

  <Step title="OCI calls Nimble for you">
    When the model decides it needs the web, OCI calls the Nimble tool directly and feeds the results back to the model. Your code receives the final, grounded answer.
  </Step>
</Steps>

### Parameters

<AccordionGroup>
  <Accordion title="base_url" icon="link">
    `https://inference.generativeai.<region>.oci.oraclecloud.com/openai/v1`. Use the region where your project and API key live, for example `us-chicago-1` or `us-ashburn-1`.
  </Accordion>

  <Accordion title="project" icon="folder">
    **Required.** The OCID of your OCI Generative AI project, which starts with `ocid1.generativeaiproject`. The OpenAI SDK sends it as the `OpenAI-Project` header.
  </Accordion>

  <Accordion title="authorization" icon="key">
    **Required.** Your Nimble API key, with no `Bearer` prefix. Oracle states that OCI does not store or log MCP authorization tokens.
  </Accordion>

  <Accordion title="allowed_tools" icon="filter">
    **Optional.** Limits which Nimble tools the model sees. Fewer tools means a shorter prompt, lower cost, and faster responses. Keep it set. Without it, the model also sees tools that start paid crawls or delete Web Search Agents. With `require_approval: never`, those run without confirmation. See the [MCP server docs](/integrations/mcp-server/mcp-server#tools) for what each product covers.
  </Accordion>

  <Accordion title="require_approval" icon="circle-check">
    **Optional.** Set to `never` so OCI runs Nimble tools without pausing for approval.
  </Accordion>

  <Accordion title="model" icon="microchip">
    **Required.** Any OCI Generative AI model that supports the Responses API, such as `openai.gpt-oss-120b`. Meta models do not support the Responses API.
  </Accordion>
</AccordionGroup>

## Resources

<CardGroup cols={2}>
  <Card title="OGX" icon="server" href="/integrations/connectors/ogx">
    The agentic API server behind the chat agent, and its Nimble provider settings.
  </Card>

  <Card title="Nimble MCP Server" icon="plug" href="/integrations/mcp-server/mcp-server">
    Tools, authentication, and setup for other MCP clients.
  </Card>

  <Card title="OCI AI Accelerator Starter Packs" icon="github" href="https://github.com/oci-ai-incubations/ai-accelerator-starter-packs">
    Oracle's Terraform stacks, including the Managed Enterprise Chat Agent.
  </Card>

  <Card title="MCP calling in OCI Generative AI" icon="book-open" href="https://docs.oracle.com/en-us/iaas/Content/generative-ai/mcp.htm">
    Oracle's reference for remote MCP tools in the Responses API.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.