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 this endpoint:

https://api.globalwebindex.com/v2beta/spark-api/mcp

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_v2beta \ --url https://api.globalwebindex.com/v2beta/spark-api/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_v2beta.
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. After you allow access, Codex confirms that you are signed in.
Start Codex:
codex
Confirm the server is connected:
> /mcp
gwi_spark_v2beta should be connected. From a shell, codex mcp list shows the server URL https://api.globalwebindex.com/v2beta/spark-api/mcp with auth OAuth.
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. If the server requires sign-in, select Authenticate.

Spark API token

Use this method when you have a Spark API token. Codex reads it 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_v2beta \
  --url https://api.globalwebindex.com/v2beta/spark-api/mcp \
  --bearer-token-env-var SPARK_API_TOKEN

Add the v2beta GWI Spark MCP server with a Spark API token

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_v2beta]
url = "https://api.globalwebindex.com/v2beta/spark-api/mcp"
bearer_token_env_var = "SPARK_API_TOKEN"

Start Codex from the same environment:
codex
Confirm the server is connected:
> /mcp
gwi_spark_v2beta should be connected. From a shell, codex mcp list shows 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.

Troubleshooting

Server missing or disabled: Run codex mcp list. The URL should be https://api.globalwebindex.com/v2beta/spark-api/mcp.
OAuth not signed in: Run codex mcp login gwi_spark_v2beta 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