Use economic data in Codex

Q: Can Codex use Narwhal with an API key?

Yes, set bearer_token_env_var to NARWHAL_API_KEY in the Narwhal server table. Export the actual key in the environment that launches Codex, and Codex sends the Authorization Bearer header.

Codex can request Narwhal data through MCP, and its CLI, IDE extension and desktop app share one configuration. Set a Bearer token environment variable to connect economic indicators, currency rates and the other live groups. REST and MCP draw from the same account quota, with one request per successful call.

Quick start

Get a free key from https://narwhalapi.com/signup and export it as NARWHAL_API_KEY.
Open ~/.codex/config.toml for all projects or .codex/config.toml inside a trusted project.
Add the Narwhal server table with its URL and bearer_token_env_var set to the variable name.
Start Codex from the environment that has the exported key and ask for a specific indicator or currency rate.

MCP configuration

The [mcp_servers.narwhal] table names the hosted URL and the environment variable that holds your key. Put NARWHAL_API_KEY in bearer_token_env_var; Codex reads the value and sends it in the Authorization Bearer header.

~/.codex/config.toml

[mcp_servers.narwhal]
url = "https://api.narwhalapi.com/mcp"
bearer_token_env_var = "NARWHAL_API_KEY"

The shared user configuration lives at ~/.codex/config.toml, while a trusted project can have its own .codex/config.toml. Keep the key in the environment of the process that starts Codex, and leave only its variable name in the file.

Tools you get

Codex gets every read-only tool group through this one connection. Initialization and discovery cost no quota; each successful tool call uses one request from the same quota as a REST call.

Group	What you can ask for	Tools
Economic indicators	Ask for CPI, inflation, unemployment, labour force participation, GDP, GDP growth and trade by country; coverage differs by indicator.	`economics_get_cpi` `economics_get_inflation` `economics_get_unemployment` `economics_get_labour_force_participation` `economics_get_gdp` `economics_get_gdp_growth` `economics_get_trade` `economics_get_cpi_history` `economics_get_inflation_history` `economics_get_unemployment_history` `economics_get_labour_force_participation_history` `economics_get_gdp_history` `economics_get_gdp_growth_history` `economics_get_trade_history` `economics_read_series_observations`
Currency rates	Ask for current exchange rates, historical rates, currency conversions and rate bars for a currency pair.	`fx_get_rates` `fx_get_rate_history` `fx_convert_currency` `fx_get_rate_bars`
Commodity prices	Ask for spot prices for gold, silver, platinum, palladium, copper, WTI crude oil, and Brent crude oil, their price history, and physical palm oil prices (crude palm oil and fresh fruit bunches).	`commodities_get_spot_price` `commodities_get_price_history` `commodities_list_palmoil_physical_series` `commodities_get_palmoil_physical_price` `commodities_get_palmoil_physical_observations` `commodities_list_physical_series` `commodities_get_physical_series` `commodities_get_physical_latest` `commodities_get_physical_observations`
Releases and events	Ask for official economic release dates and event details before you plan a country briefing.	`economics_list_releases` `economics_get_release` `events_list` `events_get`
Public holidays	Ask for public holidays by country, holidays on a particular date or the next holiday.	`calendars_list_holidays` `calendars_get_holidays_on_date` `calendars_get_next_holiday`
Prediction market odds	Ask for prediction market topics and events with scalar, extreme, timing and binary outcomes, their history, and policy paths by authority.	`predictions_list_topics` `predictions_get_topic` `predictions_list_events` `predictions_get_scalar` `predictions_get_extreme` `predictions_get_timing` `predictions_get_binary` `predictions_get_scalar_history` `predictions_get_extreme_history` `predictions_get_timing_history` `predictions_get_binary_history` `predictions_get_policy_path` `predictions_get_policy_path_history`
Government bond yields	Ask for government bond yield curves for the US, the UK, Germany, Japan, and Canada through the same Narwhal connection.	`economics_get_yield_curve` `economics_get_yield_curve_history`

Example prompts

Get the latest GDP growth value for the United States.
Show the available inflation history for the United Kingdom.
Get the current USD/IDR exchange rate.
Find the next public holiday in Japan.
Get the current gold spot price.

Common workflows

Gather indicators for an Australian briefing

economics_get_cpi_history retrieves Australian CPI by period, with the index base stated for the series.

Inspect a currency pair during development

Pass USD as the base and IDR as the quote currency to fx_get_rate_bars for closed bars at the default daily interval. Set the required start to 2026-09-15 and end to 2026-09-21.

Review the next United States CPI release

Which United States CPI release falls before your meeting? Give economics_list_releases the country and a date window of up to 366 days for the official calendar entries.

Check commodity prices for an analysis

Silver spot prices come from commodities_get_spot_price, with silver and a quote currency specified in the request.

Tips

If you register the server with codex mcp add, add bearer_token_env_var to the configuration afterward because the documented add command has no Bearer token flag.
Set the Bearer variable before connecting; Codex otherwise tries OAuth sign-in by default, and Narwhal has no OAuth sign-in for MCP.
Keep the key out of prompts, configuration values and URLs; the configuration needs the environment variable name.
Use the exact endpoint https://api.narwhalapi.com/mcp with no trailing slash to avoid redirects that break some clients.

FAQ

Can Codex use Narwhal with an API key?

Yes, set bearer_token_env_var to NARWHAL_API_KEY in the Narwhal server table. Export the actual key in the environment that launches Codex, and Codex sends the Authorization Bearer header.

Do I need separate setups for Codex CLI and the desktop app?

No, the CLI, IDE extension and desktop app share the Codex configuration. The user file applies across projects, while a trusted project can use its own configuration file.

Does adding the server start OAuth sign-in?

Codex tries OAuth by default, but a configured Bearer variable makes it send the token. Narwhal requires that key and has no OAuth sign-in for MCP, so check the variable before connecting.

Troubleshooting

Symptom	Check
Narwhal does not appear in Codex	Check `[mcp_servers.narwhal]` in the user configuration, or confirm the project containing `.codex/config.toml` is trusted.
Narwhal returns `401 invalid_api_key`	A missing or wrong key gives `401 invalid_api_key` from Narwhal; check that `NARWHAL_API_KEY` is exported in the shell that starts Codex.
Codex tries to open OAuth sign-in	Add `bearer_token_env_var` to the server table and set the named environment variable before starting Codex.
The add command registered the URL but calls fail	Open `config.toml` and add the Bearer variable setting; the documented add command registers the URL without that credential setting.