Give an LLM agent access to Narwhal

Connect your agent with MCP

Narwhal uses Streamable HTTP for MCP. REST and MCP share one account, one API key and one quota, so the key you use for REST also authenticates your agent. REST uses the base URL https://api.narwhalapi.com, while the MCP connection uses https://api.narwhalapi.com/mcp. Give your MCP client the endpoint URL and send the key in the Authorization header.

1. Store your API key Get a free key at signup and keep it in the environment variable NARWHAL_API_KEY. The endpoint accepts the key only in a header, in the form Authorization: Bearer <key>.
2. Add Narwhal to Claude Code Use the HTTP transport and the Authorization header in the command. The command adds the server under the name narwhal and reads the key from NARWHAL_API_KEY. In Claude Code, use claude mcp list or /mcp to see the server connection.
   Add the MCP server

   claude mcp add --transport http narwhal https://api.narwhalapi.com/mcp --header "Authorization: Bearer ${NARWHAL_API_KEY}"

3. Use a project configuration as an alternative For a project .mcp.json, include "type": "http" along with the URL and headers. Place the Narwhal configuration under mcpServers, with narwhal as the server name. The headers entry holds the Authorization header. This is the project configuration route for Claude Code; the command above is the command-line route.
   .mcp.json for a project

   {
     "mcpServers": {
       "narwhal": {
         "type": "http",
         "url": "https://api.narwhalapi.com/mcp",
         "headers": { "Authorization": "Bearer ${NARWHAL_API_KEY}" }
       }
     }
   }

4. Set the connection in Cursor or Codex In Cursor, use .cursor/mcp.json for a project or ~/.cursor/mcp.json, with url and headers. Cursor expands ${env:NAME} in headers, so use NARWHAL_API_KEY as the environment variable name. For Codex, open ~/.codex/config.toml and use the section [mcp_servers.narwhal]. Set url = "https://api.narwhalapi.com/mcp" and bearer_token_env_var = "NARWHAL_API_KEY"; that setting names the environment variable containing your key.
5. Read the tools list Use tools/list to get the available tools; initialization identifies the server as Narwhal API. The request below sends the same Authorization header as the client configurations. Results from tool calls are structured JSON, while errors include a status, code, detail and request id.
   Request the tools list

   curl -s -X POST https://api.narwhalapi.com/mcp -H "Authorization: Bearer $NARWHAL_API_KEY" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

For economic values, the tools list includes economics_get_cpi for CPI, economics_get_inflation for inflation, economics_get_gdp_growth for GDP growth and economics_get_yield_curve for yields. Commodity tools include commodities_get_spot_price and commodities_get_price_history. For exchange rates, use fx_get_rates, fx_convert_currency or fx_get_rate_history, according to whether you need rates, a currency conversion or rate history. Use the MCP guide for the connection details.

For your own agent code, use an MCP client library to connect to the endpoint, or use REST calls as tools. The REST route uses the same Authorization header and API key. Your agent can use Narwhal's data APIs for holidays, the economic calendar, economics, commodity spot prices, exchange rates and prediction-market odds through either route.

Connect through a chat app without code

The Claude app has custom connectors with request headers in beta for some organisations. See the Claude app MCP page for that connection option. Request-header support matters here because Narwhal's endpoint takes the API key in an Authorization header. A chat app needs a way to send that header with the MCP connection.

The ChatGPT app connects to servers without a sign-in or with OAuth. It cannot use Narwhal's API-key header connection. See Narwhal for AI agents for the available options if ChatGPT is where you want to ask your data questions.

Which connection to use

Does the agent use my quota?

Yes, each successful tools/call uses exactly one request on the same key as REST; Free has 5,000 requests a month and 30 a minute. Initialization and tools/list cost no quota. Your agent's data calls and your REST calls count against the shared quota. Reading the tools list is separate from asking one of those tools for data, so you can list the available tools without using a data request.

Can the agent change data?

No, Narwhal's MCP tools are read-only. The agent can read holidays with calendars_list_holidays or calendars_get_next_holiday, and release dates with economics_list_releases. The tools list also includes predictions_list_topics, predictions_get_policy_path and events_list for prediction-market data.

What if the agent cannot connect?

Use the URL without a trailing slash and the header in the form Authorization: Bearer <key>. The URL should be https://api.narwhalapi.com/mcp, and the header should contain the key from NARWHAL_API_KEY. In Claude Code, claude mcp list shows whether the server is connected; /mcp is also available. A wrong key returns 401 invalid_api_key. For that error, the response includes the status and code along with detail and a request id.

Worked example: ask for the next US CPI release

On 24 October 2026, the next US CPI release is 10 November 2026 at 13:30 UTC. After adding the server to Claude Code, ask, "When is the next US CPI release?" The agent calls economics_list_releases for USA and answers with the release date and time.

Start with the question about the release date. Claude Code uses economics_list_releases for USA to get the calendar answer, 10 November 2026 at 13:30 UTC in this 24 October 2026 example. The tool call uses one request. If your question is about the CPI value, economics_get_cpi is the separate tool for that data; a release date comes from the release calendar.