Connect an AI Client

You can connect AI clients such as ChatGPT, OpenAI Codex, and Claude Code to the Essbase MCP server.

The client connects to the Essbase MCP endpoint over HTTPS and authenticates with an OAuth access token issued by your Oracle Identity Domain. OAuth lets the client access Essbase without storing or repeatedly sending an Essbase user name and password.

Note:

Before connecting a client, ensure you have collected the connection and OAuth details, as described in Obtain Required Connection Details.

Each client obtains the OAuth token differently:

  • ChatGPT uses a browser-based OAuth sign-in flow.
  • OpenAI Codex uses a bearer token that you generate before starting Codex.
  • Claude Code uses OAuth with a registered client ID, client secret, and callback URI.

Complete only the procedure for the client that you want to connect.

For a first connection, use the viewer access profile: 

https://<essbase-server>/essbase/rest/v1/ess-mcp?profile=viewer

The viewer profile exposes read-only tools, thus is the best profile for validating the connection.

Connect ChatGPT

Before you begin, ensure that you have:

  • The Essbase MCP endpoint
  • The authorization URL and token URL for your Oracle Identity Domain
  • The OAuth client ID and client secret
  • Permission to add a redirect URL to the confidential application in Oracle Identity Domain

To connect ChatGPT,

  1. In ChatGPT, go to Settings, then Apps, then Advanced settings.

  2. Select Create app.

  3. Enter a name and description for the connection.

  4. For Connection, select Server URL.

  5. Enter the Essbase MCP endpoint. For example:

    https://<essbase-server>/essbase/rest/v1/ess-mcp?profile=viewer

  6. For Authentication, select OAuth.

  7. Acknowledge the custom-server risk notice.

  8. Under Advanced OAuth settings, select User-Defined OAuth Client.

    Dynamic Client Registration and Client-Initiated Metadata Discovery may appear unavailable. This is expected because the Essbase MCP endpoint does not advertise a registration URL.

  9. Copy the callback URL that ChatGPT displays. It has this form:

    https://chatgpt.com/connector/oauth/<id>

  10. In the Oracle Identity Domain confidential application, add the complete callback URL as a redirect URL.

    Use the full https:// value. Relative URLs are not accepted.

  11. In ChatGPT, enter the OAuth client ID and client secret.

  12. Set the token endpoint authentication method to client_secret_post.

  13. Set the default scope to urn:opc:idm:__myscopes__.

  14. Leave the base scopes blank.

  15. Confirm the discovered authorization URL and token URL.

  16. Leave the registration URL and resource fields blank.

  17. Select Create.

  18. Open the new connection and select Sign in.

  19. Complete the Oracle Cloud sign-in flow for your identity domain. Use the federated sign-in option, such as Microsoft Active Directory, when required by your organization.

After sign-in completes, ChatGPT can discover the Essbase MCP tools allowed by the selected profile and by the signed-in user's Essbase permissions.

Connect OpenAI Codex

Codex connects to Essbase by using a bearer token stored in an environment variable. The token must be issued for the Essbase resource scope. Do not use the IDCS meta-scope that is used for browser-based OAuth flows.

Generate an Essbase Access Token

Run the following command from a shell that can reach the Oracle Identity Domain token endpoint. Replace the placeholders with values from your environment.

export ACCESS_TOKEN=$(curl -s \ -H "Authorization: Basic <base64(client-id:client-secret)>" \ -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \ --request POST "https://<identity-domain>/oauth2/v1/token" \ -d "grant_type=password&username=<oci-username>&password=<url-encoded-password>&scope=https://<identity-domain>:443/essbase" \ | sed -rn 's/.*"access_token":"([^"]+)".*/\1/p')
export ESSBASE_MCP_TOKEN="$ACCESS_TOKEN"

The scope must identify Essbase as the resource. It typically has this form: 

https://<identity-domain>:443/essbase

Register the Essbase MCP Server

Run the following:

codex mcp add essbase \ --url "https://<essbase-server>/essbase/rest/v1/ess-mcp?profile=viewer" \ --bearer-token-env-var ESSBASE_MCP_TOKEN

You can also add the server manually to:

~/.codex/config.toml

Use the following configuration:

[mcp_servers.essbase] url = "https://<essbase-server>/essbase/rest/v1/ess-mcp?profile=viewer" bearer_token_env_var = "ESSBASE_MCP_TOKEN"

The section name must be mcp_servers, with an underscore. Codex may ignore the configuration if the section name is incorrect.

Some Codex versions may also require the following:

experimental_use_rmcp_client = true

To verify the connection,

  1. Start Codex.

  2. Enter the following:

    /mcp

  3. Confirm that the Essbase Server appears and that tools are available.

OAuth tokens expire according to the Oracle Identity Domain token lifetime. The default lifetime is often 3600 seconds. Generate a new token after the current token expires unless your confidential application is configured to support refresh tokens.

Connect Claude Code

Claude Code connects to Essbase by using OAuth with pre-registered client credentials. It uses a local callback URL during sign-in. The callback port in the command must match the redirect URL registered in Oracle Identity Domain.

Register the Callback URL

In the Oracle Identity Domain confidential application, add this redirect URL:

http://localhost:8080/callback

Add the Essbase MCP Server

Run the following:

claude mcp add --transport http \ --client-id "<your-client-id>" \ --client-secret \ --callback-port 8080 \ essbase "https://<essbase-server>/essbase/rest/v1/ess-mcp?profile=viewer"

You can also add the server by using JSON:

claude mcp add-json essbase \
  '{"type":"http","url":"https://<essbase-server>/essbase/rest/v1/ess-mcp?profile=viewer","oauth":{"clientId":"<your-client-id>","callbackPort":8080,"scopes":"urn:opc:idm:__myscopes__"}}' \
  --client-secret

The --client-secret option prompts you for the client secret with masked input. Claude Code stores the secret in the operating system keychain instead of writing it to the configuration file.

For unattended setup, you can place the secret in the MCP_CLIENT_SECRET environment variable.

Ensure that:

  • The callback port is 8080.
  • The registered redirect URL is http://localhost:8080/callback.
  • The scope is urn:opc:idm:__myscopes__.

To complete the Claude Code connection,

  1. Start Claude Code.

  2. Enter the following:

    /mcp

  3. Select the Essbase connection.

  4. Complete the browser-based OAuth sign-in flow.

Claude Code stores the OAuth credentials securely and refreshes the token automatically when the identity-domain configuration permits it.

Verify the Connection

After connecting a client,

  1. Confirm that the Essbase MCP server appears in the client.

  2. Confirm that the client can discover tools.

  3. Verify that the tools match the selected access profile.

  4. Run a read-only request, such as:

    List the Essbase applications available to me.

If the connection succeeds, but a tool call is denied, check the signed-in user’s Essbase permissions. The access profile controls which tools are exposed, but Essbase security still controls which operations the user can perform.