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

# Codex CLI

## Overview

The GWI MCP server can be integrated with Codex CLI so agents can access GWI consumer insights in the CLI, the IDE extension, and the Codex surface in the ChatGPT desktop app. Those clients share `~/.codex/config.toml`.

Use the **OpenAI profile** endpoint:

```text theme={null}
https://api.globalwebindex.com/v1/spark-api/openai/mcp
```

This endpoint exposes `search`, `fetch`, `search_audiences`, and `list_datasets`.

Reference: [Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp)

## Prerequisites

Before continuing with the integration, install Codex:

* [Install the Codex CLI](https://developers.openai.com/codex/cli)

For a Spark API token, export it as `SPARK_API_TOKEN` in the shell that starts Codex.

## Authentication

Choose one of the following methods:

* [**OAuth 2.0 (recommended).**](#oauth-20) Sign in with your GWI account. Codex stores the session and refreshes it.
* [**Spark API token.**](#spark-api-token) Use an environment variable for developer or automated environments.

### OAuth 2.0

1. Add the GWI MCP server:

   ```bash theme={null}
   codex mcp add gwi_spark \
     --url https://api.globalwebindex.com/v1/spark-api/openai/mcp
   ```

   ![Add the v1 GWI Spark MCP server and start OAuth in Codex](https://mintcdn.com/gwi-c45e8f9c/Xa6BLch5pfR9v8pV/assets/images/codex/v1/oauth-start.png?fit=max\&auto=format\&n=Xa6BLch5pfR9v8pV\&q=85\&s=2560426ab904cc4b05048700aecd458b)

   > Note: this writes the server to `~/.codex/config.toml`. You can edit that file directly. A trusted project can use `.codex/config.toml` instead.
   >
   > Codex detects OAuth on this URL and starts the sign-in flow. To sign in later, run `codex mcp login gwi_spark`.

2. You'll be redirected to the GWI sign-in page. Use your GWI credentials to sign in. **If you don't have a GWI login, click Sign up to create one**

   ![GWI sign-in page for Codex OAuth](https://mintcdn.com/gwi-c45e8f9c/Xa6BLch5pfR9v8pV/assets/images/codex/v1/sign-in.png?fit=max\&auto=format\&n=Xa6BLch5pfR9v8pV\&q=85\&s=41ea6a492f2334e0dcb1fb509859d3d9)

3. Review the requested permissions and click **Allow**. Then return to the terminal.

   ![Allow Codex to access a GWI account](https://mintcdn.com/gwi-c45e8f9c/Xa6BLch5pfR9v8pV/assets/images/codex/v1/allow-access.png?fit=max\&auto=format\&n=Xa6BLch5pfR9v8pV\&q=85\&s=6171871998de9821831045d1891ec2c3)

4. Start Codex:

   ```bash theme={null}
   codex
   ```

5. Confirm the server is connected:

   ```bash theme={null}
   > /mcp
   ```

   `gwi_spark` should be connected. From a shell, `codex mcp list` shows the server URL `https://api.globalwebindex.com/v1/spark-api/openai/mcp` with auth `OAuth`.

   ![The OAuth-authenticated v1 server in the Codex server list](https://mintcdn.com/gwi-c45e8f9c/Xa6BLch5pfR9v8pV/assets/images/codex/v1/oauth-server-list.png?fit=max\&auto=format\&n=Xa6BLch5pfR9v8pV\&q=85\&s=57313956e59b880304593b720ec3b811)

6. Ask Codex to use GWI:

   ```text theme={null}
   Which GWI datasets can I query?
   ```

   Codex returns the GWI datasets available to your account.

### Spark API token

Codex reads the token from `SPARK_API_TOKEN` and sends `Authorization: Bearer`. The config file stores the variable name only.

1. Export your token before you start Codex. Keep the real value in the environment.

   ```bash theme={null}
   export SPARK_API_TOKEN="<your Spark API token>"
   ```

2. Add the GWI MCP server:

   ```bash theme={null}
   codex mcp add gwi_spark \
     --url https://api.globalwebindex.com/v1/spark-api/openai/mcp \
     --bearer-token-env-var SPARK_API_TOKEN
   ```

   ![Add the v1 GWI Spark MCP server in Codex](https://mintcdn.com/gwi-c45e8f9c/Xa6BLch5pfR9v8pV/assets/images/codex/v1/add-server.png?fit=max\&auto=format\&n=Xa6BLch5pfR9v8pV\&q=85\&s=31725747a30b1a0dc52fd955560797b2)

   > Note: this writes the server to `~/.codex/config.toml`. You can edit that file directly. A trusted project can use `.codex/config.toml` instead.
   >
   > The saved entry looks like this:

   ```toml theme={null}
   [mcp_servers.gwi_spark]
   url = "https://api.globalwebindex.com/v1/spark-api/openai/mcp"
   bearer_token_env_var = "SPARK_API_TOKEN"
   ```

3. Start Codex from the same environment:

   ```bash theme={null}
   codex
   ```

4. Confirm the server is connected:

   ```bash theme={null}
   > /mcp
   ```

   `gwi_spark` should be connected.

   ![GWI Spark connected in Codex](https://mintcdn.com/gwi-c45e8f9c/Xa6BLch5pfR9v8pV/assets/images/codex/v1/connected.png?fit=max\&auto=format\&n=Xa6BLch5pfR9v8pV\&q=85\&s=630d8a8c75664de9caadbd9083fa4d67)

   From a shell, `codex mcp list` shows the same server with bearer token env var `SPARK_API_TOKEN`.

   ![The v1 GWI Spark MCP server in the Codex server list](https://mintcdn.com/gwi-c45e8f9c/Xa6BLch5pfR9v8pV/assets/images/codex/v1/server-list.png?fit=max\&auto=format\&n=Xa6BLch5pfR9v8pV\&q=85\&s=10d802c20b6fc86627886c2f9cc8f63d)

5. Ask Codex to use GWI:

   ```text theme={null}
   Which GWI datasets can I query?
   ```

   Codex returns the GWI datasets available to your account.

The ChatGPT desktop app and the IDE extension read this same config. In the desktop app, open **Settings → MCP servers** to see `gwi_spark`. Restart Codex after you change the file.

## Troubleshooting

* **Server missing or disabled:** Run `codex mcp list`. The URL should be `https://api.globalwebindex.com/v1/spark-api/openai/mcp`.
* **OAuth not signed in:** Run `codex mcp login gwi_spark` and allow access on the GWI sign-in page.
* **401 or invalid token:** Confirm `SPARK_API_TOKEN` is set in the shell that started Codex, and that the token has not expired or been revoked.