Home / Articles

Connect an Oracle Integration Cloud MCP Server to Codex on macOS

Set up OAuth client credentials, fetch an access token, register an OIC project's MCP server in Codex and confirm its tools show up in the CLI and desktop app.

Publisher: REACTAPP.TOP8 min read1864 words

This article is published in English.

Sources: **Connect an OIC MCP Server to Codex with macOS**

Teams that already run Oracle Integration Cloud (OIC) to wire applications together can expose suitable integrations to Codex through the Model Context Protocol. Codex then discovers those integrations as tools and calls them when a question needs them. An integration that looks up an order, for example, could become a tool Codex uses to answer a question about that order, as long as the integration is set up and published correctly.

Here we connect an OIC project's MCP server to Codex on macOS. You collect a few configuration values, request an OAuth access token, register the server, and confirm that Codex can see its tools. It also covers the extra environment step the desktop app needs and what to do when the token runs out. It takes for granted that an OIC environment is available to you and that someone has already prepared an OAuth application in OCI IAM for this purpose.

The pieces involved

Four components take part:

  • Oracle Integration Cloud hosts the integrations that talk to your applications and services.
  • The OIC project's MCP server publishes integrations that are registered as Agentic AI tools.
  • Codex is the MCP client. It finds the tools and uses them when appropriate.
  • OCI Identity and Access Management (IAM) issues the OAuth access token that authenticates requests.

A request travels like this: Codex, then the OIC MCP server, then the registered integration, then the connected application.

Before Codex can reach the server, you ask OCI IAM for a short-lived access token using the OAuth application's client credentials. That token is then handed to Codex through an environment variable.

Prerequisites to settle first

Finish the OIC and identity configuration before touching the terminal. You need:

  • An OIC project with the MCP server option enabled.
  • At least one active integration registered as an Agentic AI tool.
  • The MCP server URL. Open the project in OIC, click the pencil (Edit) icon and find the field labelled "The MCP server runs at". It is a long address that combines your instance host, region and project identifier, and Step 1 shows its full shape.
  • An OCI IAM confidential OAuth application set up for client credentials, with the OIC resource scope that carries the ServiceInvoker role.
  • Its client ID, client secret and resource scope. In the OCI Console go to Identity & Security, then Domains, then the domain tied to your OIC instance, then Integrated Applications, then your confidential application. The client ID and secret are on that page. Choose Edit OAuth Configuration and look under Token Issuance Policy for the scope, which includes urn:opc:resource:consumer::all.
  • The identity domain name. In the OCI Console, click the profile icon at the top right and choose Identity Domain to see its URL, which looks like https://<identity_domain>.identity.oraclecloud.com. You only need the <identity_domain> part, without the scheme or the suffix. For https://example123.identity.oraclecloud.com, that means example123.
  • Codex, either the CLI or the desktop app, installed.
  • A macOS zsh shell, since the commands are written for it.

If anything on that list is missing, sort it out now. The connection won't work otherwise.

Step 1: prepare the terminal

Open Terminal on your Mac. Everything below assumes zsh.

Check for Codex and jq

Run:

codex --version
command -v jq

The first line should print the Codex version. The second should print the path of jq, which is used to pull the token out of the authentication response.

If jq is missing and Homebrew is installed:

brew install jq

Set your values

Swap every <angle bracket> placeholder for your own value, then run:

export OIC_CLIENT_ID='<CLIENT_ID>'
export OIC_RESOURCE_SCOPE='<RESOURCE_SCOPE>'
export OIC_IDENTITY_DOMAIN='<IDENTITY_DOMAIN>'
export OIC_MCP_URL='https://<oic-instance-host>.integration.<region>.ocp.oraclecloud.com/mcp-server/v1/projects/<project-identifier>/mcp'

What each variable means:

  • OIC_CLIENT_ID is the client ID of your OAuth confidential application.
  • OIC_RESOURCE_SCOPE holds the complete scope string as configured for OIC. It contains the urn:opc:resource:consumer::all element.
  • OIC_IDENTITY_DOMAIN is just the part before .identity.oraclecloud.com, such as example123.
  • OIC_MCP_URL is the full project-specific URL copied from the "The MCP server runs at" field.

Keep the client secret out of this block. The next step asks for it with hidden input.

Catch missing values and leftover placeholders

This block confirms all four variables hold something and none still contains an angle bracket:

(
  setup_ready=true

  for name in \
    OIC_CLIENT_ID \
    OIC_RESOURCE_SCOPE \
    OIC_IDENTITY_DOMAIN \
    OIC_MCP_URL
  do
    value="${(P)name}"

    if [[ -z "$value" || "$value" == *'<'* || "$value" == *'>'* ]]; then
      printf 'Check %s: missing value or unreplaced placeholder.\n' "$name"
      setup_ready=false
    fi
  done

  if [[ "$setup_ready" == true ]]; then
    printf 'Required values are populated and contain no placeholders.\n'
  fi
)

It only checks that values exist, not that the credentials, scope or URL are right. Leave this terminal session open, because the next step reuses these variables.

Step 2: get an OAuth access token

In the same session, run the block below. It asks for the client secret, requests a token from OCI IAM, and makes it available to the Codex CLI and to desktop apps launched afterwards. Type or paste the secret and press Return. Nothing shows on screen while you type.

read -rs 'OIC_CLIENT_SECRET?OIC client secret: '
printf '\n'

if token="$(
  curl --silent --show-error --fail \
    --user "${OIC_CLIENT_ID}:${OIC_CLIENT_SECRET}" \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode "scope=${OIC_RESOURCE_SCOPE}" \
    "https://${OIC_IDENTITY_DOMAIN}.identity.oraclecloud.com:443/oauth2/v1/token" \
  | jq -er '.access_token'
)"; then
  unset OIC_CLIENT_SECRET
  export OIC_ACCESS_TOKEN="$token"
  unset token

  if launchctl setenv OIC_ACCESS_TOKEN "$OIC_ACCESS_TOKEN"; then
    echo 'Access token received and set for CLI and newly launched desktop apps.'
  else
    echo 'Access token set for CLI, but desktop environment setup failed.' >&2
  fi
else
  unset OIC_CLIENT_SECRET token
  echo 'ERROR: Token request failed. Check your values and OAuth configuration.' >&2
fi

On success it prints:

Access token received and set for CLI and newly launched desktop apps.

Because the prompt is silent, the secret never lands in your shell history, and the script wipes the secret variable once the token request finishes.

Confirm the token exists

This check reports presence without ever printing the token:

[[ -n "$OIC_ACCESS_TOKEN" && "$OIC_ACCESS_TOKEN" != 'null' ]] \
  && echo 'OIC access token is present' \
  || echo 'ERROR: OIC access token is missing'

It proves the variable has a value. Whether OIC accepts the token is only settled when Codex actually talks to the server.

For the desktop app, quit Codex fully and reopen it after launchctl setenv has succeeded so it sees the updated environment.

Treat the token as a secret. Don't echo it to the terminal, and don't paste it into chats, email, tickets or documents.

Step 3: register the server in Codex

With a token in hand, run this in the same session:

codex mcp add oic \
  --url "$OIC_MCP_URL" \
  --bearer-token-env-var OIC_ACCESS_TOKEN

That adds the server to Codex under the name oic, using the URL from Step 1. With --bearer-token-env-var, Codex looks up the token in the OIC_ACCESS_TOKEN variable when it connects. Give it the variable's name without a dollar sign, so the stored configuration refers to the variable and doesn't capture today's token value.

Step 4: check the configuration

List the configured servers and inspect the new one:

codex mcp list
codex mcp get oic

Make sure that:

  • the server is called oic and is enabled;
  • the URL matches your OIC project's MCP endpoint;
  • the transport is streamable_http;
  • the bearer-token variable is OIC_ACCESS_TOKEN.

If the server is absent, disabled or aimed at the wrong URL, fix that before moving on.

Step 5: find the tools from the CLI

Launch Codex from the terminal where OIC_ACCESS_TOKEN was exported, so it inherits the token:

codex

When it opens, enter this prompt:

List the tools available from every MCP server with oic in its name.

You should see a list of the tools exposed by your OIC project. If the list comes back empty, go back to OIC and verify that an active integration in the project is registered as an Agentic AI tool. When Codex complains about authentication instead, recheck the OAuth setup, repeat Step 2 for a fresh token, and restart Codex from that terminal.

Step 6: use it from the desktop app

Before opening the app, make sure Step 2 is done, including this command:

launchctl setenv OIC_ACCESS_TOKEN "$OIC_ACCESS_TOKEN"

If it already succeeded during Step 2, there's no need to repeat it. Quit the desktop app completely and start it again so it can read the token. Both clients use the same MCP configuration, yet a variable exported in just one terminal session never reaches the desktop app by itself.

Start a new Codex task and type:

/mcp

Check that oic appears, then send the same discovery prompt:

List the tools available from every MCP server with oic in its name.

Codex should list the tools from your OIC project.

When the token expires

The access token is short-lived, and its lifetime follows your OCI IAM settings. To renew the connection:

  1. Go back to the setup terminal, or re-enter the Step 1 values.
  2. Repeat Step 2 to get a new token and update the desktop environment.
  3. Quit and reopen the desktop app. For CLI use, start a fresh Codex session from the terminal that holds the new token.

The server doesn't need to be registered again unless its configuration was removed or changed.

Troubleshooting notes

A few failure patterns come up repeatedly with this kind of setup:

  • A token request that fails immediately usually means a wrong client ID, secret or scope, or an identity domain value that still includes the https:// prefix or the suffix.
  • A token that works in the CLI but not in the app almost always means the desktop environment wasn't updated, or the app wasn't restarted after the update.
  • An empty tool list with no error usually points to the OIC side: the project's MCP server isn't enabled or no integration has been registered as an Agentic AI tool.
  • Authentication errors that start after a while of working normally are most likely an expired token, so repeat Step 2.