Documentation

Invokely exposes the same five operations through an MCP server and a REST API. Every figure comes with its period, unit and source. Claude.ai and ChatGPT connect with OAuth; other clients use an API key.

Quick start

1. Create an account and copy your API key from the dashboard. /login
2. Add the MCP server to your client with one of the configurations below.
3. Ask a question such as: what is the unemployment rate in Texas and how does it compare with California and the United States?

Endpoints

• https://invokely.ai/mcp. MCP server (Streamable HTTP). Requires an API key or OAuth.
• https://invokely.ai/mcp/trial. MCP server without an account, 25 calls a day per IP address.
• https://invokely.ai/api/v1. REST API. Same operations, same metering.

Authentication

Send the API key as Authorization: Bearer ivk_... or as an x-api-key header. Clients that cannot set headers, such as Claude.ai and ChatGPT connectors, use OAuth: add the server URL and sign in when asked.

Client configuration

Claude Code

claude mcp add --transport http invokely https://invokely.ai/mcp --header "Authorization: Bearer YOUR_API_KEY"

Claude Desktop and Claude.ai

In Claude.ai or Claude Desktop, open Settings, Connectors, Add custom connector, and paste the URL. You will be asked to sign in to Invokely.

https://invokely.ai/mcp

ChatGPT

In ChatGPT, enable developer mode, create a connector with the URL below and choose OAuth. Sign in to Invokely when prompted.

https://invokely.ai/mcp

Cursor

{
  "mcpServers": {
    "invokely": {
      "url": "https://invokely.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

VS Code

{
  "servers": {
    "invokely": {
      "type": "http",
      "url": "https://invokely.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Tools

search_indicators

Find official statistical indicators by natural language, in English or Spanish. Use this first when you do not know the exact indicator id.
Coverage: Spain (municipalities, provinces, regions, national), EU countries, and the United States (nation, states, counties). Topics: population and demography, unemployment and employment, prices and inflation, income, GDP, housing, companies, tourism, interest rates, public finance.
Pass geography when the question is about a specific place: indicators not published at that place's level are ranked lower.
Example: {"query": "tasa de paro", "geography": "Mataró"}.
Returns {indicators: [{id, name, unit, frequency, levels, definition, note?}]}. Read note: it explains common confusions, such as survey unemployment rate versus registered unemployment.

resolve_place

Turn a place name into the normalized entity Invokely uses, with its official codes (INE, Idescat, NUTS, ISO, US FIPS) and parent.
Use it when a name is ambiguous or you want to confirm which entity a number refers to. The other tools accept names directly, so this call is optional.
Ambiguous names prefer the municipality ("Barcelona" is the city); the province and region come back in alternatives. Ask for "provincia de Barcelona" to get the province.
US states are regions and US counties are provinces. Names shared by several places of the same level, such as "Washington County", return an AMBIGUOUS_PLACE error with suggestions; add the state ("Washington County, Oregon") or pass a suggested id.
Example: {"name": "Mataró"}. Returns {match: {id, name, level, country, population, parent, codes}, alternatives: [{id, name, level}]}.

get_value

Get one official figure for an indicator and place: the latest by default, or a given period.
Use it for questions like "population of Mataró", "inflation in Spain in 2024-09", "unemployment rate in Cataluña", "unemployment rate in Texas".
Example: {"indicator": "population", "place": "Mataró"}.
Returns {indicator: {id, name, unit}, place: {id, name, level}, period, value, status?, source: {name, title, url, retrieved, published?, citation, inputs?}, note?}.
Always cite source.citation or source.url when you answer. status "provisional" or "estimated" means the figure may be revised; say so.
If the indicator is not published for that place you get an error that names the levels where it exists and related indicators that do have data.

get_series

Get the time series of an indicator for one place, oldest to newest, from one source so the points are comparable.
Use it for trends: "evolution of the CPI by month", "population of Mataró since 2015".
Example: {"indicator": "cpi_annual_change", "place": "España", "from": "2023-01"}.
Returns {indicator, place, frequency, points: [[period, value], ...], total_points, truncated?, flags?: {period: status}, source, other_frequencies?}.
Free and Builder plans receive the latest 60 points; truncated says when history was cut.

compare

Compare one indicator across 2 to 10 places for the same period, using one shared source and definition whenever possible.
Use it for "how does X compare with Y and Z". Places can mix levels, for example a city, a larger city and its region.
Example: {"indicator": "registered_unemployment_rate", "places": ["Mataró", "Barcelona", "Cataluña"]}.
Returns {indicator, period, comparable, values: [{place, value, status?}], source, notes?}. When comparable is false the values come from different sources or periods and notes explain why; mention it in your answer.
For unemployment in municipalities use registered_unemployment_rate: the survey unemployment_rate is not published below province level.

REST API

All data endpoints use GET and return {"data": ...} or {"error": {code, message, hint?}}. The remaining allowance is sent in the x-invokely-remaining header.

curl -H "Authorization: Bearer YOUR_API_KEY" "https://invokely.ai/api/v1/value?indicator=population&place=California"

Response format

Responses are compact JSON. Every value carries a source block with the publisher, dataset title, URL, retrieval date and a ready-made citation. Derived indicators list their inputs.

Citation rules for agents

Quote the period and cite source.citation or source.url. Mention status when a figure is provisional or estimated. When compare returns comparable false, say that the values come from different sources or periods.

Errors

Errors carry a code (INVALID_ARGUMENT, INDICATOR_NOT_FOUND, PLACE_NOT_FOUND, NO_DATA, QUOTA_EXHAUSTED, RATE_LIMITED), a message, and often a hint and suggestions the agent can act on.

Limits

Free 500, Builder 10,000 and Pro 60,000 calls a month, plus prepaid credits. Burst limits are 30, 120 and 300 requests a minute. Free and Builder series return the latest 60 points.

• Methodology
• OpenAPI
• llms.txt