Connect through MCP

Use the same Narwhal key and economics schemas from an MCP client.

Narwhal exposes one stateless Streamable HTTP MCP endpoint. It uses the same economics use cases, response schemas, authentication, and quota as REST.

Connect

Add the remote server URL and Bearer header to an MCP client that supports authenticated Streamable HTTP.

Client-neutral field map

{
  "url": "https://api.narwhalapi.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_NARWHAL_API_KEY"
  }
}

This is a field map, not a copy-paste file. Replace YOUR_NARWHAL_API_KEY through your client's secure secret setting. JSON does not expand shell variables by itself, and MCP clients use different environment-variable syntax.

Do not paste a real key into a shared configuration file.

Available tools

tools/list returns exactly these nine read-only tools:

economics_get_cpieconomics_get_inflationeconomics_get_unemploymenteconomics_get_labour_force_participationeconomics_get_gdpeconomics_get_gdp_growtheconomics_get_tradeeconomics_get_trade_exportseconomics_get_trade_imports

Arguments and results

Every tool accepts country and optional period. The accepted period format depends on the operation.

Tool arguments

{
  "country": "USA",
  "period": "2026-07"
}

For the two directional trade tools, MCP uses "product": { "classification": "HS2022", "code": "27" }. REST represents the same filter as separate classification and product query parameters.

Tool	Period	Other arguments
`economics_get_cpi`	`YYYY-MM`	None
`economics_get_inflation`	`YYYY-MM`	None
`economics_get_unemployment`	`YYYY, YYYY-MM, or YYYY-QN`	None
`economics_get_labour_force_participation`	`YYYY, YYYY-MM, or YYYY-QN`	None
`economics_get_gdp`	`YYYY-QN`	None
`economics_get_gdp_growth`	`YYYY-QN`	None
`economics_get_trade`	`YYYY or YYYY-MM`	None
`economics_get_trade_exports`	`YYYY or YYYY-MM`	`partner` and nested `product` are accepted, but filtered totals are not yet published.
`economics_get_trade_imports`	`YYYY or YYYY-MM`	`partner` and nested `product` are accepted, but filtered totals are not yet published.

Successful tool calls return schema-valid structuredContent plus the same JSON serialized as text for client compatibility. MCP problems use the same public status and code vocabulary as REST.

Quota behavior

Initialization and tool discovery do not consume data quota. Each successful tools/call consumes exactly one request, just like one successful REST call.

Quota state is returned in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers.

Troubleshooting

Symptom	Check
`401 invalid_api_key`	Confirm the exact Bearer header and that the key is still active.
Connection follows a redirect	Use exactly `https://api.narwhalapi.com/mcp` without a trailing slash.
Tool is missing	Only the nine economics tools above are public during beta.
Tool returns a problem	Read its structured status, code, detail, and request ID. See Errors and quota.