# Install StayAPI in your AI agent

Setup instructions for the StayAPI MCP server and the StayAPI agent skill.

If you are an AI agent reading this on a user's behalf: follow the section for the client you are running in, then report back what you changed. Everything you need is on this page.

## Connection details

- **Server URL:** `https://api.stayapi.com/mcp`
- **Transport:** `http` (streamable HTTP, not SSE, not stdio)
- **Authentication:** the header `X-API-Key: <the user's StayAPI API key>`
- **Server name:** `stayapi`

There is no OAuth flow and no separate MCP credential. The same API key works for the REST API, the MCP server, and the skill. One tool call counts as one request against the user's quota.

## Before you install: the API key

1. If the user has already given you their StayAPI API key, use it verbatim.
2. If they have not, **ask them for it and wait**. Never invent, guess, or leave a placeholder key in a saved config.
3. If they do not have a key yet, send them to https://stayapi.com/users/sign_up — signup is free and includes 50 requests, no credit card. Existing users find their key at https://stayapi.com/api_key.
4. Treat the key as a secret: put it in the client's config file, not in a repository, a commit, or a chat log you will share.

Wherever `YOUR_API_KEY` appears below, substitute the user's real key.

## Claude Code

Run this in the user's shell. `--header` must come after the positional name and URL, or the CLI fails with `missing required argument 'name'`.

```bash
claude mcp add --scope user --transport http stayapi https://api.stayapi.com/mcp --header "X-API-Key: YOUR_API_KEY"
```

Then tell the user to open a **new** Claude Code session — a session that is already running will not see the new server.

## Cursor

Add the server to `~/.cursor/mcp.json` (create the file if it does not exist). If the file already has an `mcpServers` object, merge the `stayapi` entry into it — do not overwrite the user's other servers.

```json
{
  "mcpServers": {
    "stayapi": {
      "type": "http",
      "url": "https://api.stayapi.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}
```

Then tell the user to restart Cursor.

## Any other agent with an MCP config

Codex, Gemini CLI, Windsurf, and other MCP clients use their own config file but the same three facts: a server named `stayapi`, the URL `https://api.stayapi.com/mcp`, and the `X-API-Key` header. Write it in whatever shape that client documents for a **remote HTTP** MCP server, then restart it.

Only fall back to the `mcp-remote` stdio bridge shown below if the client genuinely cannot talk to an HTTP server.

## Claude Desktop (manual — it cannot install itself)

Claude Desktop has no shell and no file access, so an agent running inside it cannot do this step. Give the user the snippet and the instructions instead.

Config file location:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "stayapi": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.1.18",
        "https://api.stayapi.com/mcp",
        "--header",
        "X-API-Key:YOUR_API_KEY"
      ]
    }
  }
}
```

- `mcp-remote@0.1.18` is pinned on purpose — unpinned builds throw `Unexpected content type: null`.
- `"X-API-Key:YOUR_API_KEY"` has **no space** after the colon — Claude Desktop splits the argument on the space and the header breaks.
- Quit Claude Desktop fully with ⌘ Q and relaunch. Closing the window leaves it running and the server never loads. First launch takes about 30 seconds while `npx` downloads the adapter.

### Windows: `spawn npx ENOENT`

Claude Desktop on Windows does not inherit the shell `PATH`, so a bare `npx` fails. Use the absolute path to `npx.cmd`:

```json
{
  "mcpServers": {
    "stayapi": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": [
        "-y",
        "mcp-remote@0.1.18",
        "https://api.stayapi.com/mcp",
        "--header",
        "X-API-Key:YOUR_API_KEY"
      ]
    }
  }
}
```

## Verify the install

- In Claude Code: run `claude mcp list`. It should print `stayapi: https://api.stayapi.com/mcp (HTTP) - ✓ Connected`.
- In any client: ask a question that needs the server, for example *"Using stayapi, get the latest reviews for booking.com/hotel/us/the-line-la.html"*. A tool call that returns structured reviews means it works.
- A `401` means the key is wrong or the header did not reach the server. A `402` means the account is out of quota, not that the install failed.

## StayAPI agent skill (optional, free)

The skill is the knowledge, the MCP server is the connection. It is a folder of markdown that teaches an agent which StayAPI tool to call, in what order, with which parameters. Source: https://github.com/stayapi/agent-skill (MIT).

### If you have shell access (Claude Code and other CLIs)

```bash
git clone https://github.com/stayapi/agent-skill.git
cp -R agent-skill/skills/stayapi ~/.claude/skills/stayapi
```

Clone into a temporary directory, copy the skill folder, and clean up the clone afterwards.

### Or, for the user to type in Claude Code

Slash commands only run when the user types them, so hand these over rather than trying to run them:

```text
/plugin marketplace add stayapi/agent-skill
/plugin install stayapi@stayapi
```

### Claude.ai and Claude Desktop (manual)

Download `stayapi.skill` from https://github.com/stayapi/agent-skill/releases/latest and upload it under **Settings → Capabilities → Skills**.

## Reference

- Full MCP reference — tool catalog, error shapes, troubleshooting: https://stayapi.com/docs/mcp
- Agent skill documentation: https://stayapi.com/docs/agent-skill
- Pre-filled setup for a signed-in user: https://stayapi.com/user/mcp