MCP Quickstart

Get an MCP-aware LLM client talking to Hostex in five minutes. Pick your client and follow the matching block.

MCP endpoint: https://hostex.io/mcp
Transport:    Streamable HTTP (a.k.a. http)

Get an Access Token first (if you're not using OAuth)

1. Log in at https://hostex.io/app/dashboard.
2. Open the OpenAPI Settings page.
3. Create an Access Token. Choose read-only for "just let the AI answer questions" or writable to also let it create/update/cancel/send messages.
4. Copy the token — it's only shown once. Treat it like a password.

If your client supports OAuth (Claude Code, Claude Desktop, Cursor, mcp-inspector, Codex), you can skip this step and let the client open a browser to authenticate against the Host Portal instead.

Client support matrix

Claude Code (CLI)

Claude Code is Anthropic's command-line agent.

With a Hostex Access Token

claude mcp add --transport http hostex https://hostex.io/mcp \
  --header "Authorization: Bearer YOUR_HOSTEX_ACCESS_TOKEN"

That's it — open claude and the Hostex tools are available immediately.

The --header flag must come before the server name (hostex). This is a Claude Code CLI quirk; if you reverse the order it silently passes the flag to the server instead.

With OAuth (no token in config)

claude mcp add --transport http hostex https://hostex.io/mcp

Then inside Claude Code run:

/mcp

Pick hostex from the list — Claude Code opens a browser to the Host Portal authorization page, you approve, and the OAuth refresh token is stored in Claude's secure credential store. No token ever lands in ~/.claude.json.

Scope it to one project (optional)

The commands above install the server in your local scope (this machine, all projects). To share with your team via .mcp.json:

claude mcp add --transport http --scope project hostex https://hostex.io/mcp

Codex CLI

Codex is OpenAI's command-line agent. Native HTTP MCP support landed in late 2025 — make sure you're on a recent version (codex --version).

With a Hostex Access Token

Edit ~/.codex/config.toml:

[mcp_servers.hostex]
url                  = "https://hostex.io/mcp"
bearer_token_env_var = "HOSTEX_MCP_TOKEN"
enabled              = true

Then in your shell rc (~/.zshrc, ~/.bashrc, …):

export HOSTEX_MCP_TOKEN="YOUR_HOSTEX_ACCESS_TOKEN"

Restart your terminal and run codex — Hostex tools are available.

Codex reads the token from the environment variable, not from the config file. This keeps secrets out of your dotfiles. If you prefer a CLI command instead of editing TOML:

Bash

codex mcp add hostex --url https://hostex.io/mcp \
  --bearer-token-env-var HOSTEX_MCP_TOKEN

With OAuth (no token in config)

# ~/.codex/config.toml
[mcp_servers.hostex]
url     = "https://hostex.io/mcp"
enabled = true

Then:

codex mcp login hostex

Codex opens the Host Portal authorization page in your browser; the OAuth refresh token is stored in Codex's secure credential store.

Claude Desktop

Edit claude_desktop_config.json:

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

With a Hostex Access Token

Claude Desktop's GUI does not speak Streamable HTTP natively yet, so use the mcp-remote bridge (it runs locally and proxies to the Hostex endpoint):

{
  "mcpServers": {
    "hostex": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://hostex.io/mcp",
        "--header",
        "Authorization:${HOSTEX_MCP_TOKEN}"
      ],
      "env": {
        "HOSTEX_MCP_TOKEN": "Bearer YOUR_HOSTEX_ACCESS_TOKEN"
      }
    }
  }
}

Restart Claude Desktop. Hostex tools appear in the tools panel.

With OAuth

Same config, just drop the header:

{
  "mcpServers": {
    "hostex": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://hostex.io/mcp"]
    }
  }
}

On first use, a browser window opens at https://hostex.io/app/authorization; sign in and approve. The token is cached by mcp-remote and auto-refreshed.

Cursor

Open Settings → Features → Model Context Protocol → Add new MCP server.

With a Hostex Access Token

{
  "name": "hostex",
  "transport": "streamable-http",
  "url": "https://hostex.io/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_HOSTEX_ACCESS_TOKEN"
  }
}

With OAuth

{
  "name": "hostex",
  "transport": "streamable-http",
  "url": "https://hostex.io/mcp"
}

Cursor pops the authorization page on first use.

mcp-inspector

For quick poking and debugging:

With a Hostex Access Token

npx @modelcontextprotocol/inspector \
  --transport streamable-http \
  --url https://hostex.io/mcp \
  --header "Authorization: Bearer YOUR_HOSTEX_ACCESS_TOKEN"

With OAuth

npx @modelcontextprotocol/inspector \
  --transport streamable-http \
  --url https://hostex.io/mcp

The inspector prints an authorization URL — open it in a browser, approve, and copy the resulting code back into the inspector prompt.

Verify your connection

Ask the model:

"List the first three Hostex properties."

It should call the search_properties tool and return your top three properties with id, title, and connected channels.

For a slightly heavier smoke test:

"Show me reservations checking in next week."

The model should call search_reservations with start_check_in_date / end_check_in_date covering the next 7 days in your operator's timezone.

What you can ask (examples)

Each Hostex tool ships with intent_examples (typical user phrasings) so most plain-English requests just work. Things proven out of the box:

• "Any unread messages from John?" → search_conversations + get_conversation
• "Reply to this guest: the lock code is 6688." → send_message
• "Add a note on this thread: VIP guest, confirm late check-in." → update_conversation_note
• "Block property #1234 next weekend." → update_availabilities
• "Create a cleaning task for tomorrow on this reservation." → create_task with stay_code
• "Show recent low-rating reviews." → search_reviews
• "How much did property #1234 earn last quarter?" → search_transactions with date filters
• "Add a knowledge entry: WiFi password is HostexGuest." → create_knowledge_base

Browse the Tools Reference for the full catalog and the example phrases registered for each tool.

Troubleshooting

For deeper issues, see Errors — the MCP transport wraps the same error_code / error_msg envelope as the REST API inside the JSON-RPC result.content body.

Where to go next

• MCP Overview — protocol details, scope semantics, what's exposed vs not.
• Tools Reference — every tool with parameters, since-version, and example phrases.
• OAuth Authorization Workflow — what's happening when your MCP client OAuths in.