Setup guide · Remote MCP server

Set Up the AirROI MCP Server in Any Client

One URL and one header work in 10+ clients. Copy the config for yours, confirm the tools load, and ask your first question.

Get your API keyFind your client

MCP protocol 2025-11-25Registry com.airroi/mcp

Works with

  • Claude
  • Codex
  • Cursor
  • VS Code
  • Antigravity
  • n8n

What every client needs

Endpoint
https://mcp.airroi.com
Header
X-API-KEY
Value
Your AirROI API key
Transport
Streamable HTTP, stateless
Name it
airroi

Every client uses these values; only the config file differs.

Clients with setup steps
14
Remote URL
1
X-API-KEY header
1
Servers to install
0

Before you start

You need three things: an AirROI API key, created in the developer dashboard after a $10 credit deposit; an MCP client that can call a remote HTTP server with a custom header; and the endpoint https://mcp.airroi.com with the X-API-KEY header.

Setup takes under two minutes in most clients.

An AirROI API key

Create it in the developer dashboard after a $10 minimum deposit. Calls start at $0.01, priced like the REST API. tools/list isn't billed but still needs the key.

Get your API key · How to get an API key

A client that sends a custom header

It must call a remote Streamable HTTP server and attach X-API-KEY to every request. ChatGPT on the web can't: developer mode takes only OAuth or no-auth servers.

See every client

One endpoint, one header

https://mcp.airroi.com plus the X-API-KEY header. No package, no local server. Name the entry airroi so tool calls read clearly.

Protocol details

New to MCP? Read the Airbnb MCP server overview, or compare Airbnb MCP servers to see how market data differs from scrapers and PMS servers.

Every client at a glance

The AirROI MCP server works in any client that reaches a remote Streamable HTTP server and attaches an X-API-KEY header. The table covers 14 clients as of September 2026: where each keeps its config, where the key goes and the gotcha to watch for.

Client support for header-authenticated remote MCP servers.
ClientStatusHow to connectConfig locationKey goes inWatch out for
Claude Code
Connect Claude to Airbnb data		Worksclaude mcp add --transport http … --header~/.claude.json (user scope) or .mcp.json (project scope)Header flagNeeds a Pro, Max, Team, Enterprise or Console account
Claude Desktop
Connect Claude to Airbnb data		Works via mcp-remotemcp-remote bridge in claude_desktop_config.json~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows)env blockNo spaces around the colon in --header; needs Node.js; restart the app
Claude on the web and mobile
Connect Claude to Airbnb data		Limited (beta)Custom connector set to No sign-in, with the key under Request headers (beta, limited to some organizations)Customize → Connectors (Team and Enterprise: owners add it under Organization settings → Connectors)x-api-key request headerRequest headers are a limited beta; community reports the header is sometimes not sent (anthropics/claude-ai-mcp #644)
Codex in the ChatGPT desktop app
Use Airbnb data in Codex and ChatGPT		WorksSettings → MCP servers → Add server, or edit the TOML~/.codex/config.tomlenv_http_headers (recommended) or http_headersSame file as the CLI; restart after editing
Codex CLI
Use Airbnb data in Codex and ChatGPT		Works[mcp_servers.airroi] block in config.toml~/.codex/config.toml; project .codex/config.toml in trusted projects onlyenv_http_headerscodex mcp add has no header flag; "Auth: Unsupported" in codex mcp list is expected
Codex IDE extension
Use Airbnb data in Codex and ChatGPT		WorksGear menu → MCP servers, or the shared TOML~/.codex/config.tomlenv_http_headersVS Code detection bug (openai/codex #6465)
ChatGPT on the web (developer mode)
Use Airbnb data in Codex and ChatGPT		Not supportedNot supported for API-key servers—OAuth, No Authentication or Mixed onlyDoesn't read config.toml; use Codex instead
Cursor
Worksmcp.json with url + headers~/.cursor/mcp.json or .cursor/mcp.json${env:AIRROI_API_KEY}Enable the server and check its tools under Customize in the sidebar
VS Code (Copilot agent mode)
Works.vscode/mcp.json with "servers" and "type": "http"Workspace or user settings${input:airroi-key} password promptThe key is servers, not mcpServers
Devin Desktop (formerly Windsurf)
WorksserverUrl + headers~/.config/devin/mcp_config.json (Windows: %APPDATA%\devin\mcp_config.json)${env:AIRROI_API_KEY}Renamed from Windsurf on June 2, 2026; older guides still show the ~/.codeium/windsurf path
Antigravity CLI (Gemini CLI's successor)
WorksserverUrl + headers~/.gemini/config/mcp_config.json (global) or .agents/mcp_config.json (project)headers objectGemini CLI retired for consumer accounts on June 18, 2026; url and httpUrl became serverUrl
n8n
WorksMCP Client Tool node → HTTP Streamable → Header Authn8n credentialsHeader name X-API-KEYLimit the agent to the tools the workflow needs
OpenAI Agents SDK (Python)
WorksMCPServerStreamableHttp(params={url, headers})Your codeEnvironment variableStateless server: no session to keep alive
Any stdio-only client
Works via mcp-remotenpx mcp-remote bridgeThe client's config fileenvSame bridge as Claude Desktop

Claude Code and Claude Desktop

Claude Code adds AirROI with one terminal command, and --scope user makes it available in every project. Claude Desktop reads a JSON config and reaches the server through the mcp-remote bridge, which needs Node.js.

The full Claude guide covers plans, the web connector and a first real session.

Config
~/.claude.json (user) or .mcp.json (project)
Key
The --header flag
Check
/mcp or claude mcp list
  1. Run the command with your key in place of the highlighted placeholder, then check with /mcp.
  2. Claude Desktop: add the mcp-remote entry from the stdio section to ~/Library/Application Support/Claude/claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json) and restart the app.
Terminalbash
claude mcp add --transport http airroi \
  https://mcp.airroi.com \
  --header "X-API-KEY: YOUR_API_KEY" --scope user

Need Claude Code first?

The native installer is recommended: curl -fsSL https://claude.ai/install.sh | bash, or irm https://claude.ai/install.ps1 | iex in PowerShell. npm still works with Node.js 22 or later. Claude Code needs a Pro, Max, Team, Enterprise or Console account.

Full guide:Connect Claude to Airbnb data

Checked against the Claude Code MCP docs.

Codex (ChatGPT desktop app, CLI, IDE)

Codex reads MCP servers from ~/.codex/config.toml, one file shared by the ChatGPT desktop app, the Codex CLI and the IDE extension. env_http_headers pulls your key from the AIRROI_API_KEY environment variable.

ChatGPT on the web can't connect, because developer mode sends no API-key headers.

Config
~/.codex/config.toml
Key
env_http_headers → AIRROI_API_KEY
Check
/mcp or codex mcp list
  1. Export AIRROI_API_KEY, then paste the block into ~/.codex/config.toml or add it in the desktop app under Settings → MCP servers.
  2. Restart Codex and type /mcp. "Auth: Unsupported" in codex mcp list is expected.
Shell profile (~/.zshrc or ~/.bashrc)bash
export AIRROI_API_KEY=YOUR_API_KEY
~/.codex/config.tomltoml
[mcp_servers.airroi]
url = "https://mcp.airroi.com"
env_http_headers = { "X-API-KEY" = "AIRROI_API_KEY" }

ChatGPT on the web can't send your key

Developer mode accepts OAuth, No Authentication or Mixed only and doesn't read config.toml. Use Codex instead.

Full guide:Use Airbnb data in Codex and ChatGPT

Checked against OpenAI's Codex MCP docs.

Cursor

Cursor reads remote servers from ~/.cursor/mcp.json for every project or .cursor/mcp.json for one. Add an airroi entry with url and headers.

Cursor resolves ${env:AIRROI_API_KEY} in both fields, so the key stays in your shell profile, not the file. Then confirm the tools under Customize in the sidebar.

Config
~/.cursor/mcp.json (global) or .cursor/mcp.json (project)
Key
headers via ${env:AIRROI_API_KEY}
Check
Customize in the sidebar
  1. Export AIRROI_API_KEY in your shell profile, then quit and reopen Cursor.
  2. Paste the block into ~/.cursor/mcp.json, or add just the airroi entry to an existing mcpServers.
  3. Open Customize and check that airroi is enabled with 29 tools.
  4. Ask in Agent chat. Cursor asks before running MCP tools by default.
~/.cursor/mcp.jsonjson
{
  "mcpServers": {
    "airroi": {
      "url": "https://mcp.airroi.com",
      "headers": { "X-API-KEY": "${env:AIRROI_API_KEY}" }
    }
  }
}

Sharing it with a repository?

Use .cursor/mcp.json and keep the ${env:AIRROI_API_KEY} reference so nobody commits a key.

Checked against Cursor's MCP docs.

VS Code (Copilot agent mode)

VS Code reads MCP servers from .vscode/mcp.json in a workspace, or your user mcp.json for all workspaces. The top-level key is servers, not mcpServers, and HTTP servers need "type": "http".

An inputs entry with "password": true asks for your key once and keeps it out of the file.

Config
.vscode/mcp.json, or MCP: Open User Configuration
Key
${input:airroi-key} password prompt
Check
Configure Tools in the chat input
  1. Create .vscode/mcp.json, or run MCP: Open User Configuration to cover every workspace.
  2. Paste the block and choose Start in the inline actions above the entry.
  3. Enter your key when prompted for airroi-key.
  4. In Copilot Chat, switch to Agent and open Configure Tools to see the airroi tools.
.vscode/mcp.jsonjson
{
  "inputs": [
    {
      "type": "promptString",
      "id": "airroi-key",
      "description": "AirROI API key",
      "password": true
    }
  ],
  "servers": {
    "airroi": {
      "type": "http",
      "url": "https://mcp.airroi.com",
      "headers": { "X-API-KEY": "${input:airroi-key}" }
    }
  }
}

servers, not mcpServers

Pasting a Cursor or Claude config is the usual mistake. Only the portable .mcp.json at the workspace root uses mcpServers.

Checked against the VS Code MCP docs.

Devin Desktop (formerly Windsurf)

Devin Desktop, called Windsurf until June 2, 2026, connects to remote servers with a serverUrl field and a headers object in mcp_config.json. It resolves ${env:AIRROI_API_KEY} in headers, so the key can stay in your shell profile.

Open the file from the MCPs section of the agent panel's … menu.

Config
~/.config/devin/mcp_config.json (Windows: %APPDATA%\devin\mcp_config.json)
Key
headers via ${env:AIRROI_API_KEY}
Check
MCPs section of the … (Actions) menu
  1. In the agent panel, open the … (Actions) menu and choose Open MCP config file. It opens the file your install reads.
  2. Add the airroi entry with serverUrl; Devin also accepts url.
  3. Export AIRROI_API_KEY, restart and check the tool count in the MCPs section.
  4. The agent can use 100 tools across all servers, and AirROI adds 29. Trim others with disabledTools.
~/.config/devin/mcp_config.jsonjson
{
  "mcpServers": {
    "airroi": {
      "serverUrl": "https://mcp.airroi.com",
      "headers": { "X-API-KEY": "${env:AIRROI_API_KEY}" }
    }
  }
}

Which path does your install read?

Devin's docs list ~/.config/devin/mcp_config.json. Installs carried over from Windsurf also read ~/.codeium/windsurf/mcp_config.json during the transition.

Checked against Devin's MCP docs.

Antigravity CLI (replaces Gemini CLI)

Antigravity CLI replaced Gemini CLI for Google AI Pro, Ultra and free individual accounts on June 18, 2026. It reads MCP servers from ~/.gemini/config/mcp_config.json, shared with the Antigravity IDE, or .agents/mcp_config.json in a workspace.

Remote servers need serverUrl plus a headers object for X-API-KEY.

Config
~/.gemini/config/mcp_config.json (global) or .agents/mcp_config.json (workspace)
Key
headers, stored in the file
Check
/mcp in agy
  1. Open ~/.gemini/config/mcp_config.json, creating it if needed. The global file keeps the key out of repositories.
  2. Add the airroi entry with serverUrl and your key in headers.
  3. Run agy and type /mcp to check that airroi is connected.
  4. Using .agents/mcp_config.json? Add it to .gitignore; the docs describe no env-var references for headers.
~/.gemini/config/mcp_config.json (global) or .agents/mcp_config.json (project)json
{
  "mcpServers": {
    "airroi": {
      "serverUrl": "https://mcp.airroi.com",
      "headers": { "X-API-KEY": "YOUR_API_KEY" }
    }
  }
}

Coming from Gemini CLI?

Rename url or httpUrl to serverUrl after agy plugin import gemini. On a paid Gemini API key, Gemini CLI still works with httpUrl and headers in ~/.gemini/settings.json.

Checked against Google's Antigravity MCP docs.

n8n

n8n connects through the MCP Client Tool node attached to an AI Agent node. Point it at https://mcp.airroi.com with the HTTP Streamable transport and a Header Auth credential named X-API-KEY.

The agent then chooses from all 29 tools, or only the ones you select for that workflow.

  1. Add an AI Agent node, then attach an MCP Client Tool node to it.
  2. Set the endpoint to https://mcp.airroi.com and the transport to HTTP Streamable.
  3. Choose Header Auth and create a credential with name X-API-KEY and your key as the value.
  4. Optionally limit the tools to the ones your workflow needs, then run the agent.

Two node details

Nodes created at version 1 show an SSE Endpoint field; add a fresh node to get Server Transport. For a fixed step with no agent, the MCP Client node calls one tool.

MCP Client Tool node settings, checked against n8n's node source.
FieldSet it to
Endpointhttps://mcp.airroi.com
Server TransportHTTP Streamable
AuthenticationHeader Auth
Credential nameX-API-KEY
Credential valueYour AirROI API key
Tools to IncludeSelected, then pick what the workflow needs

One r/n8n builder chained five MCP servers to rate cities for Airbnb investment and had to raise the agent's iteration limit to 30. Market tools return occupancy, ADR and revenue directly.

Checked against n8n's MCP Client Tool docs.

Your own agent (OpenAI Agents SDK and others)

The server is stateless, so any MCP SDK that speaks Streamable HTTP and sets custom headers can call it without keeping a session alive. Pass the URL and an X-API-KEY header read from an environment variable.

The OpenAI Agents SDK and Claude Agent SDK examples below each answer one market question.

OpenAI Agents SDK (Python)

MCPServerStreamableHttp takes the URL and headers in params. Add cache_tools_list=True to skip re-listing tools on each run.

agent.py (OpenAI Agents SDK)python
import asyncio, os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="airroi",
        params={
            "url": "https://mcp.airroi.com",
            "headers": {"X-API-KEY": os.environ["AIRROI_API_KEY"]},
        },
    ) as airroi:
        agent = Agent(name="STR analyst", mcp_servers=[airroi])
        result = await Runner.run(
            agent, "Occupancy and ADR for 2-bedroom homes in Nashville?"
        )
        print(result.final_output)

asyncio.run(main())

Checked against the Agents SDK MCP docs.

Claude Agent SDK (TypeScript)

Use type: "http" in mcpServers and allow the tools with mcp__airroi__*; MCP tools you haven't allowed won't run.

agent.ts (Claude Agent SDK)typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Occupancy and ADR for 2-bedroom homes in Nashville?",
  options: {
    mcpServers: {
      airroi: {
        type: "http",
        url: "https://mcp.airroi.com",
        headers: { "X-API-KEY": process.env.AIRROI_API_KEY ?? "" },
      },
    },
    allowedTools: ["mcp__airroi__*"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Checked against the Claude Agent SDK MCP docs.

Building an app instead? The REST endpoints behind each tool share the same key and balance. For what teams build, see Airbnb MCP use cases.

Clients that only run local (stdio) servers

Some clients only launch local stdio servers. For those, run mcp-remote, a small Node.js bridge that starts through npx and forwards each request to https://mcp.airroi.com with your header.

It's the only package involved; AirROI publishes none. Write the header with no spaces around the colon.

  1. Install Node.js 18 or later so npx is on the client's PATH.
  2. Add the entry with the mcp-remote command and your key in env.
  3. Write X-API-KEY:${AIRROI_API_KEY} without spaces; some clients, and Windows, don't escape them in args.
  4. --header-file reads headers from a file, one Name: value per line, to keep the key off the command line.
Client config (mcpServers entry)json
{
  "mcpServers": {
    "airroi": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.airroi.com",
        "--header",
        "X-API-KEY:${AIRROI_API_KEY}"
      ],
      "env": { "AIRROI_API_KEY": "YOUR_API_KEY" }
    }
  }
}
Any stdio-only clientbash
npx mcp-remote https://mcp.airroi.com --header X-API-KEY:${AIRROI_API_KEY}

Checked against the mcp-remote README.

Check that it works

Once connected, your client lists 29 AirROI tools. tools/list isn't billed but still needs the key, so an empty list or an error means the header didn't arrive. Then ask one small question: the 2-call Lisbon market check below, run against the live server, cost $0.11.

Where each client shows the tool list.
ClientWhere to look
Claude Code/mcp or claude mcp list
Codex/mcp or codex mcp list
CursorCustomize in the sidebar
VS CodeConfigure Tools in the chat input
Devin DesktopMCPs section of the agent panel's … menu
Antigravity CLI/mcp in agy
n8nTools to Include fills from the server

Next, try a revenue estimate with comps, a competitor's live calendar or a base price recommendation.

Investor

Size up a market outside the US

Prompt

How does a 1-bedroom entire apartment perform on Airbnb in Lisbon? Give me occupancy, ADR and annual revenue in euros.

2 tool calls

  1. airroi_search_markets$0.01

    query: Lisbon

  2. airroi_market_summary$0.10

    Lisbon, Lisbon, Portugal · room_type = entire_home · bedrooms = 1 · num_months: 12 · currency: native

Answer written from these results

Over the last 12 months, 1-bedroom entire homes in Lisbon averaged 57% occupancy at an ADR of €130.60, for RevPAR of €77.20 and about €20,600 in average annual revenue per listing. Guests book 49 days ahead on average and stay 5.1 nights, against an average minimum stay of 4.1 nights. The segment has about 5,120 active listings.

Run against mcp.airroi.com · 2 calls · cost $0.11

Troubleshooting

Most setup failures come down to the header. "401 Missing API key" means a request reached AirROI without X-API-KEY; a server that never appears means the client couldn't parse its config.

Match your symptom below, then restart the client fully after each change, since most clients read their config only at launch.

Symptoms and fixes, checked against each client's docs.
SymptomLikely causeFix
401 {"error":"Missing API key"}The header never arrived.Name it exactly X-API-KEY, inside headers or the --header flag.
The key reference arrives emptyAIRROI_API_KEY isn't set where the client launched.Export it in your shell profile, then quit and reopen the client.
mcp-remote exits or mangles the headerSpaces around the colon split the argument.Write X-API-KEY:${AIRROI_API_KEY}. Spaces are fine inside env.
The server never shows upThe config uses another client's key names.VS Code: servers. Cursor, Claude Desktop: mcpServers + url. Devin Desktop, Antigravity: mcpServers + serverUrl.
Codex shows "Auth: Unsupported"Expected for header auth.Nothing to fix; /mcp lists the tools.
Claude Desktop says the server failedNode.js or npx is missing, or the JSON has a typo.Read the logs: ~/Library/Logs/Claude/mcp*.log (macOS), %APPDATA%\Claude\logs (Windows).
Antigravity lists the server, but tools failAn imported Gemini config still says url or httpUrl.Rename it to serverUrl and restart agy.
ChatGPT on the web has no field for the keyDeveloper mode takes OAuth or no-auth servers only.Use Codex in the ChatGPT desktop app, CLI or IDE.

Protocol details

AirROI runs a remote, stateless MCP server over Streamable HTTP only: no stdio package and no SSE endpoint. It negotiates MCP protocol version 2025-11-25, checks the X-API-KEY header on every request and is listed in the official MCP Registry as com.airroi/mcp.

Here are the details client and SDK authors ask about.

Endpoint
https://mcp.airroi.com; /mcp works too.
Transport
Streamable HTTP only, stateless, with no Mcp-Session-Id. Legacy HTTP+SSE is deprecated in the current MCP specification.
Protocol version
2025-11-25, negotiated on initialize (official TypeScript SDK 1.30.0).
Authentication
X-API-KEY on every request, including initialize and tools/list. No OAuth, no key in the query string.
Tools
29 tools: 26 carry readOnlyHint, and the other 3 create a download file or scan cursor. None can change a listing, price, booking or message. See Airbnb analytics MCP tools.
Billing
From $0.01 per call after a $10 deposit, the same per-call pricing as the REST API. tools/list isn't billed.
Registry
com.airroi/mcp in the official MCP Registry.

Frequently asked questions

Three things: an AirROI API key (created in the developer dashboard after a $10 credit deposit); an MCP client that supports remote HTTP servers with custom headers; and the endpoint, https://mcp.airroi.com, with the header X-API-KEY. Setup takes under two minutes in most clients.

Add an airroi entry under mcpServers in ~/.cursor/mcp.json (global) or .cursor/mcp.json (project), with "url": "https://mcp.airroi.com" and a headers object that sets X-API-KEY to ${env:AIRROI_API_KEY}. Export AIRROI_API_KEY in your shell profile and restart Cursor. Then open Customize in the sidebar and confirm that airroi lists its 29 tools.

Create .vscode/mcp.json with a servers entry (not mcpServers) of "type": "http", "url": "https://mcp.airroi.com" and an X-API-KEY header. Use an inputs password prompt, ${input:airroi-key}, so the key isn't saved in the file. Choose Start above the server entry, enter your key when asked, and use the tools in Copilot Chat's Agent mode.

Open the MCP config file from the MCPs section of the agent panel's … menu, then add an airroi server with "serverUrl": "https://mcp.airroi.com" and a headers object containing X-API-KEY. Devin's docs place the file at ~/.config/devin/mcp_config.json (Windows: %APPDATA%\devin\mcp_config.json), and installs carried over from Windsurf also read ~/.codeium/windsurf/mcp_config.json. Windsurf was renamed Devin Desktop on June 2, 2026.

Gemini CLI stopped serving Google AI Pro, Ultra and free individual accounts on June 18, 2026. Its replacement, Antigravity CLI, works with AirROI: add the server to ~/.gemini/config/mcp_config.json (or .agents/mcp_config.json in a workspace) with "serverUrl": "https://mcp.airroi.com" and an X-API-KEY header. Older Gemini configs used url or httpUrl; Antigravity needs serverUrl.

Yes. Attach an MCP Client Tool node to your AI Agent, then set Endpoint to https://mcp.airroi.com and Server Transport to HTTP Streamable. Choose Header Auth and create a credential with name X-API-KEY and your key as the value. The agent can then call any of the 29 tools, and Tools to Include limits it to the few your workflow needs.

The server didn't receive the X-API-KEY header. Every request needs it, including the first initialize and tools/list. Check three things: the header name is exactly X-API-KEY; your environment variable is exported in the shell that starts the client; and, with mcp-remote, there are no spaces around the colon.

It speaks Streamable HTTP only, the transport the MCP specification recommends for remote servers. The older HTTP+SSE transport is deprecated in the current specification. If your client only supports local stdio servers, run the mcp-remote bridge (npx mcp-remote https://mcp.airroi.com --header X-API-KEY:${AIRROI_API_KEY}), the same approach as in Claude Desktop.

Get your API key

Add $10 in credit, paste your client's config and ask your first market question. One key covers the MCP server and the REST API.

Create an API keyBrowse the tools