MCP 快速开始

让一个支持 MCP 的 LLM 客户端在 5 分钟内连上百居易。选择你的客户端，照着对应小节配置即可。

MCP 端点：    https://www.myhostex.com/mcp
传输协议：    Streamable HTTP (即 http)

先获取 Access Token（如果不走 OAuth）

1. 登录 https://www.myhostex.com/app/dashboard。
2. 打开 OpenAPI 设置页。
3. 创建一个 Access Token。"只让 AI 回答问题" 选 只读；如果还需要让它创建 / 更新 / 取消订单 / 发消息，选 可写。
4. 复制 Token——只展示一次，请像密码一样保管。

如果你的客户端支持 OAuth（Claude Code / Desktop、Cursor、mcp-inspector、Codex），可以跳过这一步，让客户端通过浏览器自行在百居易后台完成授权。

客户端支持矩阵

Claude Code（命令行）

Claude Code 是 Anthropic 的命令行 Agent。

用 Access Token

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

完成。打开 claude，百居易的工具立刻可用。

--header 必须放在 server 名（hostex）之前。这是 Claude Code CLI 的一个怪点；顺序反了会被当作给服务端的参数。

用 OAuth（配置里不放 Token）

claude mcp add --transport http hostex https://www.myhostex.com/mcp

随后在 Claude Code 中执行：

/mcp

从列表里挑 hostex——Claude Code 会打开浏览器跳转到百居易后台授权页，确认后 OAuth refresh token 会保存到 Claude 的安全凭据库中，不会落到 ~/.claude.json。

限定到单个项目（可选）

上面的命令默认安装到 本地 scope（本机所有项目）。要随项目分享（写进 .mcp.json）：

claude mcp add --transport http --scope project hostex https://www.myhostex.com/mcp

Codex CLI

Codex 是 OpenAI 的命令行 Agent。原生 HTTP MCP 支持是 2025 年末才落地的，请确保使用较新版本（codex --version）。

用 Access Token

编辑 ~/.codex/config.toml：

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

再在 shell rc（~/.zshrc、~/.bashrc 等）中：

export HOSTEX_MCP_TOKEN="YOUR_HOSTEX_ACCESS_TOKEN"

重启终端运行 codex，百居易工具即可用。

Codex 从 环境变量 读取 Token，而不是从配置文件——避免密钥落入 dotfiles。如果更喜欢用 CLI：

Bash

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

用 OAuth（配置里不放 Token）

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

然后：

codex mcp login hostex

Codex 会打开浏览器跳到百居易后台授权页；refresh token 保存在 Codex 的安全凭据库。

Claude Desktop

编辑 claude_desktop_config.json：

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

用 Access Token

Claude Desktop 的 GUI 还不能原生说 Streamable HTTP，需要用 mcp-remote 桥接（本机跑，代理到百居易端点）：

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

重启 Claude Desktop，百居易工具会出现在 Tools 面板里。

用 OAuth

同样的配置，去掉 header：

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

第一次使用会弹出浏览器到 https://www.myhostex.com/app/authorization；登录授权即可。Token 由 mcp-remote 缓存并自动刷新。

Cursor

打开 Settings → Features → Model Context Protocol → Add new MCP server。

用 Access Token

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

用 OAuth

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

Cursor 在首次使用时会自动弹出授权页。

mcp-inspector

用于快速验证与排查：

用 Access Token

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

用 OAuth

npx @modelcontextprotocol/inspector \
  --transport streamable-http \
  --url https://www.myhostex.com/mcp

inspector 会打印一个授权 URL——在浏览器里打开授权后，把回调里的 code 粘回 inspector 即可。

验证连接

问模型：

"列出前 3 个百居易房间。"

模型应该会调用 search_properties 工具，返回前 3 个房间的 id、名称、连接的渠道。

更进一步的烟囱测试：

"查下下周入住的订单。"

模型应该会带着 start_check_in_date / end_check_in_date 覆盖未来 7 天调用 search_reservations（按你账号的时区）。

你可以这样问（示例）

每个百居易工具都附带 intent_examples（典型用户语句），多数自然语言请求都能直接命中。一些已经验证过开箱即用的例子：

• "看下张三有没有未读消息。" → search_conversations + get_conversation
• "回复房客：门锁密码是 6688。" → send_message
• "给这条会话加备注：VIP 客户，确认晚到入住。" → update_conversation_note
• "下周末把房间 #1234 锁掉。" → update_availabilities
• "给这单生成一个明天的保洁任务。" → create_task 带 stay_code
• "看下最近的低分评价。" → search_reviews
• "上一季度房间 #1234 收入多少？" → search_transactions 带日期过滤
• "新增一条知识库：WiFi 密码是 HostexGuest。" → create_knowledge_base

完整工具目录和示例语句见 工具参考。

排查

更深入的问题请参阅 错误码 ——MCP 传输层会把 error_code / error_msg 信封原样塞到 JSON-RPC 的 result.content 中。

下一步

• MCP 概览 —— 协议细节、scope 语义、暴露 / 不暴露的接口范围。
• 工具参考 —— 每个工具的参数、since-version 与示例语句。
• OAuth 授权流程 —— MCP 客户端做 OAuth 时具体发生了什么。