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:

https://api.globalwebindex.com/v1/spark-api/openai/mcp

This endpoint exposes search, fetch, search_audiences, and list_datasets. Reference: Codex MCP documentation

Prerequisites

Before continuing with the integration, install Codex:

Install the 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). Sign in with your GWI account. Codex stores the session and refreshes it.
Spark API token. Use an environment variable for developer or automated environments.

OAuth 2.0

Add the GWI MCP server:
codex mcp add gwi_spark \ --url https://api.globalwebindex.com/v1/spark-api/openai/mcp
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.
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
Review the requested permissions and click Allow. Then return to the terminal.
Start Codex:
codex
Confirm the server is connected:
> /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.
Ask Codex to use GWI:
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.

Export your token before you start Codex. Keep the real value in the environment.
export SPARK_API_TOKEN="<your Spark API token>"

Add the GWI MCP server:

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

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:

[mcp_servers.gwi_spark]
url = "https://api.globalwebindex.com/v1/spark-api/openai/mcp"
bearer_token_env_var = "SPARK_API_TOKEN"

Start Codex from the same environment:
codex
Confirm the server is connected:
> /mcp
gwi_spark should be connected. From a shell, codex mcp list shows the same server with bearer token env var SPARK_API_TOKEN.
Ask Codex to use GWI:
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.

​Overview

​Prerequisites

​Authentication

​OAuth 2.0

​Spark API token

​Troubleshooting