Client Setup

Configure the Hotel Universe MCP server in your AI tool of choice. All integrations use the same endpoint and Bearer token.

Prerequisites

• A Personal Access Token — see Authentication
• MCP endpoint: https://api.hotel-universe.travel/mcp

---

Claude Code (the CLI) supports HTTP MCP servers natively — no bridge or extra packages needed.

Add the server

claude mcp add --transport http hotel-universe \
  https://api.hotel-universe.travel/mcp \
  --header "Authorization: Bearer pat_YOUR_TOKEN"

This stores the server in local scope by default (private to your current project, saved in ~/.claude.json).

Scope options

Scope	Command flag	Where stored	Use when
local (default)	(omit --scope)	~/.claude.json	Personal access, not shared
project	--scope project	.mcp.json in project root	Shared with your team via git
user	--scope user	~/.claude.json	Available across all your projects

For a team setup, use project scope and reference the token via an environment variable so the file is safe to commit:

claude mcp add --transport http hotel-universe --scope project \
  https://api.hotel-universe.travel/mcp \
  --header "Authorization: Bearer \${HOTEL_UNIVERSE_TOKEN}"

Then set HOTEL_UNIVERSE_TOKEN=pat_… in your shell or .env.

The resulting .mcp.json in your project root looks like:

{
  "mcpServers": {
    "hotel-universe": {
      "type": "http",
      "url": "https://api.hotel-universe.travel/mcp",
      "headers": {
        "Authorization": "Bearer ${HOTEL_UNIVERSE_TOKEN}"
      }
    }
  }
}

Managing servers

claude mcp list              # list all configured servers
claude mcp get hotel-universe  # inspect a specific server
claude mcp remove hotel-universe  # remove a server

Inside a Claude Code session, run /mcp to see connection status and available tools for all configured servers.

No graphical UI

MCP server management in Claude Code is entirely CLI-based. The /mcp slash command inside a session is the closest thing to a status view.

Claude Desktop uses a stdio-based MCP transport internally, so connecting to a remote HTTP server requires the mcp-remote bridge package. Node.js 18+ must be installed.

Config file locations:

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

{
  "mcpServers": {
    "hotel-universe": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.hotel-universe.travel/mcp",
        "--header",
        "Authorization: Bearer pat_YOUR_TOKEN"
      ]
    }
  }
}

Steps:

1. Ensure Node.js 18+ is installed (node --version).
2. Open or create the Claude Desktop config file at the path above.
3. Add the hotel-universe entry and replace pat_YOUR_TOKEN.
4. Quit and relaunch Claude Desktop.
5. Verify: start a new conversation and ask "What Hotel Universe tools do you have?" — Claude should list all 12 tools.

Why mcp-remote?

Claude Desktop requires MCP servers to speak stdio (stdin/stdout). The mcp-remote package acts as a local bridge: it starts a stdio-compatible process that forwards calls to the Hotel Universe HTTP endpoint. This is the standard approach for connecting Claude Desktop to remote MCP servers.

Cursor supports MCP servers via a JSON config file. Add the Hotel Universe server to your project-local or global Cursor config.

Config file locations:

• Project: .cursor/mcp.json (in your project root)
• Global: ~/.cursor/mcp.json

{
  "mcpServers": {
    "hotel-universe": {
      "url": "https://api.hotel-universe.travel/mcp",
      "headers": {
        "Authorization": "Bearer pat_YOUR_TOKEN"
      }
    }
  }
}

Steps:

1. Create or edit .cursor/mcp.json in your project root (or the global file).
2. Paste the block above and replace pat_YOUR_TOKEN with your token.
3. Restart Cursor or open the Command Palette → MCP: Reload Servers.
4. Verify: open the Cursor chat, type @hotel-universe — the 12 Hotel Universe tools should appear in the autocomplete.

Project vs global config

Use the project file (.cursor/mcp.json) for team repos — add it to .gitignore if your token is personal. Use the global file (~/.cursor/mcp.json) for access across all projects.

Codex Desktop (and the Codex CLI) use a TOML config file. MCP servers with Bearer token auth are configured via bearer_token_env_var, which points to an environment variable holding your token — keeping the token out of the config file.

Config file locations:

• Global: ~/.codex/config.toml
• Project: .codex/config.toml

[mcp_servers.hotel-universe]
url = "https://api.hotel-universe.travel/mcp"
bearer_token_env_var = "HOTEL_UNIVERSE_TOKEN"

Steps:

1. Set your token as an environment variable:

   export HOTEL_UNIVERSE_TOKEN=pat_YOUR_TOKEN
   

   Add this line to your ~/.zshrc (or ~/.bashrc) to make it permanent.
2. Edit ~/.codex/config.toml (or the project-level file) and add the block above.
3. Restart Codex Desktop.
4. Verify: ask Codex "List your available tools" — Hotel Universe tools should appear.

Why an environment variable?

Codex reads bearer_token_env_var as the name of an env var, then injects its value as the Authorization: Bearer header at request time. This keeps your token out of the config file, which is safe to commit.

Windsurf reads MCP server configuration from a JSON file.

Config file location:

• ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "hotel-universe": {
      "serverUrl": "https://api.hotel-universe.travel/mcp",
      "headers": {
        "Authorization": "Bearer pat_YOUR_TOKEN"
      }
    }
  }
}

Steps:

1. Edit (or create) ~/.codeium/windsurf/mcp_config.json.
2. Add the hotel-universe entry and replace pat_YOUR_TOKEN.
3. Restart Windsurf.
4. Verify: open the Cascade panel and check that Hotel Universe tools are listed.

Any client that can send JSON-RPC over HTTP can call the MCP server directly. This is useful for scripting, Postman collections, or custom integrations.

List available tools

curl -X POST https://api.hotel-universe.travel/mcp \
  -H "Authorization: Bearer pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Call a tool

curl -X POST https://api.hotel-universe.travel/mcp \
  -H "Authorization: Bearer pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search_hotels_natural_language",
      "arguments": {
        "query": "4-star hotels in Barcelona with a rooftop pool"
      }
    }
  }'

---

Troubleshooting

Symptom	Likely cause	Fix
HTTP 401 on every call	Token missing or malformed	Check the Authorization: Bearer pat_… header format
HTTP 403 on every call	Token lacks hotels:view	Verify account permissions or contact hello@ubio.ai
HTTP 402 on get_hotel	Trial limit reached (100 hotels)	Upgrade at hello@ubio.ai
HTTP 402 on get_metasearch_pricing	No metasearch subscription	Contact hello@ubio.ai
Tools not appearing in Cursor	Config file not loaded	Check JSON syntax; restart Cursor; confirm file is in .cursor/mcp.json
Claude Desktop shows no tools	mcp-remote not installed or Node missing	Run node --version and npx mcp-remote --version to verify
Claude Code shows no tools	Server not added or wrong scope	Run claude mcp list; re-add if missing
Unknown tool error in response	Tool name typo	Call tools/list to confirm exact tool names