MCP 概览

受众：在百居易之上构建 LLM 集成的开发者，以及直接读这页的 LLM Agent。百居易 OpenAPI v3 中所有操作类接口都同步暴露为 Model Context Protocol（MCP）工具——支持 MCP 的客户端可以用自然语言驱动百居易，无需任何胶水代码。

TL;DR

mcp_endpoint:         https://www.myhostex.com/mcp
transport:            streamable-http      # MCP HTTP 传输，JSON-RPC over text/event-stream
auth:
  bearer_token:       https://www.myhostex.com/app/api/open-api   # 创建 Access Token，作为 Authorization: Bearer … 发送
  oauth:              auto-discovery       # 由端点按 RFC 9728 + 8414 + 7591 自动发现
tools:
  total:              72
  read_only:          27                   # 任何 Access Token 都能调用
  writable:           45                   # 需要可写 Access Token
  requires_confirm:   31                   # 在 writable 子集中，建议客户端弹出确认
categories:           [reservation, property, calendar, finance, task,
                       knowledge_base, messaging, automation, meta]
ai_friendly_surface:
  site_index:         https://api-doc.myhostex.com/llms.txt
  raw_markdown:       https://api-doc.myhostex.com/reference/{slug}.md   # 任一页面，例如 mcp-overview.md
  openapi_spec:       https://api.myhostex.com/v3/config.cn.json        # 完整 spec，含 x-mcp 块
  tools_catalog:      https://api-doc.myhostex.com/reference/mcp-tools-reference.md

如果你做的不是 LLM 集成，可以忽略本页，直接使用 REST 接口。两套接口共用同一份鉴权、scope、限流和审计日志。

机器可读资源（给 AI Agent）

百居易对外开放了几份规范化资源，Agent 可以直接消费，不必爬 HTML：

资源	URL	内容
站点索引	`https://api-doc.myhostex.com/llms.txt`	llms.txt 格式。每页一行，标题 + 短描述，可直接喂给 RAG 流水线或 LLM 上下文。
每页的纯 Markdown	`https://api-doc.myhostex.com/reference/{slug}.md`	任意 reference 页 URL 末尾加 `.md` 即拿到原始 Markdown，`text/markdown` 返回。比 HTML 更适合 embedding。
OpenAPI 3 spec	`https://api.myhostex.com/v3/config.cn.json`	完整 spec，含每个操作的 `x-mcp` 扩展块。工具、参数、示例以及 `read_only` / `requires_confirmation` 标记都以此为准。
MCP 工具目录	`https://api-doc.myhostex.com/reference/mcp-tools-reference.md`	每个工具一节 H3，含底层接口、副作用类型、自哪个版本起暴露、完整描述以及示例语句（`intent_examples`）。

MCP 自动发现链路本身也是机器可读的，遵循公开 RFC，Agent 仅凭 https://www.myhostex.com/mcp 一个 URL 就能完成接入。

为什么是 MCP

MCP 是一份开放协议，标准化了模型如何发现和调用外部工具。一个 HTTP 端点上双向跑 JSON-RPC，客户端能拿到：

类型化的工具目录（名称、描述、JSON Schema 参数、副作用标记）。
长任务的流式进度。
每个工具的意图示例（"用户说什么时候调它"）。
标准的 OAuth 2.1 + PKCE 流程，配合自动发现——终端用户在浏览器里授权一次，客户端永远见不到密码。

百居易 MCP 层在每个暴露的 v3 接口基础上额外提供下列元数据：

字段	用途
`tool_name`	LLM 友好的 snake_case 名（例如 `search_reservations` 而不是 `query-reservations`）。
`description`	自然语言描述，重点是让 LLM 判断何时应该调用，而不仅仅是怎么调。
`intent_examples`	房东可能说出的、会触发该工具的语句。
`requires_confirmation`	不可逆 / 写密集操作上会被打上这个标记，客户端应当先向用户确认。
`read_only`	该工具是否只读，便于客户端在 "禁止写" 模式下过滤。
`category`	粗分类，用于 UI 展示（分布见下）。
`since_version`	该工具首次出现在哪个 v3 版本。便于与 Changelog 对齐。

这些信息位于 OpenAPI spec 中每个操作的 x-mcp 块，REST 消费方不会受影响。

端点

https://www.myhostex.com/mcp

服务端使用 Streamable HTTP 传输（当前 MCP 的 HTTP 变种）。POST 返回 text/event-stream 形式的 JSON-RPC；GET 或未鉴权请求会返回 WWW-Authenticate: Bearer realm="...", resource_metadata="https://www.myhostex.com/.well-known/oauth-protected-resource/mcp"，MCP 客户端据此自动发现 OAuth 流程（RFC 9728）。

自动发现端点

标准 MCP 客户端只需要 https://www.myhostex.com/mcp 这一个 URL，之后会自动读取：

URL	规范	提供的内容
`https://www.myhostex.com/.well-known/oauth-protected-resource/mcp`	RFC 9728	指向授权服务器。
`https://www.myhostex.com/.well-known/oauth-authorization-server/mcp`	RFC 8414	授权、token、注册、撤销端点。
`POST https://api.myhostex.com/v3/oauth/registrations`	RFC 7591	动态客户端注册——返回固定的 `hostex_mcp` 公共 client_id。

通常不需要你手动调用——Claude Code、Claude Desktop、Cursor、mcp-inspector、各官方 SDK 等都会透明完成。客户端配置见 MCP 快速开始。

鉴权

两种等价的拿到 Bearer Token 的方式：

你拥有的	怎么做
在百居易后台（"AI 助手 Token" 页面）签发的 Access Token	直接在每次 MCP 请求里发 `Authorization: Bearer <token>`，跳过 OAuth。
自身就能跑 OAuth 的客户端（Claude Code / Desktop、Cursor、mcp-inspector、官方 SDK、Codex）	让客户端指向 `https://www.myhostex.com/mcp`。客户端会顺着上面的发现链路打开百居易后台授权页面，并把 Token 保存到自己的安全凭据库。

OAuth 走的是 公共客户端 + PKCE（不需要 client secret）。发现到的授权端点是百居易后台的同意页；token 端点是 POST https://api.myhostex.com/v3/oauth/authorizations；撤销是 POST https://api.myhostex.com/v3/oauth/revoke。完整请求 / 响应详情见 OAuth 授权流程。

Scope 语义

工具继承所用 Access Token 的 scope：

Token scope	可用工具
`read-only`	27 个查询工具（所有 `read_only: true` 的——搜索、获取、列表）。
`writable`	全部 72 个工具。

任何创建 / 更新 / 删除 / 发送消息 / 改变状态的工具都需要可写 Token。其中 31 个还带有 requires_confirmation: true——客户端应当在执行前弹出 "确认要这么做吗？" 的提示。

暴露了哪些工具

总共 72 个工具，全部由 spec 中 x-mcp.exposed: true 的接口自动产生。按 category 分布：

Category	工具数	示例
`reservation`	18	`search_reservations`、`cancel_reservation`、`approve_reservation`、`update_check_in_details`、`add_reservation_tag`
`property`	13	`search_properties`、`create_property`、`search_room_types`、`update_property_group`
`calendar`	10	`get_property_availability`、`update_listing_prices`、`update_listing_restrictions`
`finance`	8	`create_transaction`、`search_transactions`、`query_income_methods`
`task`	8	`create_task`、`update_task`、`delete_task`、`query_staffs`
`knowledge_base`	5	`create_knowledge_base`、`update_knowledge_base`（HostGPT 用）
`messaging`	4	`query_conversations`、`send_message`、`update_conversation_note`
`automation`	3	`query_upcoming_automation_actions`、`execute_automation_action`
`meta`	3	`query_tags`、`query_custom_fields`、`query_custom_channels`

完整目录（含每个工具的参数和示例语句）见工具参考（直接从 spec 自动生成，始终最新）。程序化消费请取 https://api-doc.myhostex.com/reference/mcp-tools-reference.md。

哪些没有暴露

OAuth 自身（/oauth/*）——客户端自己处理 OAuth，没必要把它包成工具。
Webhook 管理（/webhooks/*）——基础设施级配置应该在后台做，不交给 LLM。
渠道账号凭据等纯运营私密配置。

MCP 服务端是 v3 REST API 之上的一层极薄代理——没有额外业务逻辑、校验或限流窗口。一次工具调用最终命中和 REST 调用相同的 Controller，返回相同的 JSON，并计入相同的 Token 级配额。

一次工具调用长什么样

完成鉴权后，针对 search_reservations 的一次 MCP tools/call（被客户端序列化后）形如：

POST /mcp HTTP/1.1
Host: www.myhostex.com
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_reservations",
    "arguments": {
      "start_check_in_date": "2026-06-01",
      "end_check_in_date":   "2026-06-08",
      "status":              "accepted"
    }
  }
}

服务端返回事件流，最后一条 data: 携带：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"request_id\":\"...\",\"data\":{\"reservations\":[ ... ]}}"
      }
    ],
    "isError": false
  }
}

里面的 text 就是 GET /reservations 会返回的内容——MCP 不会改造响应结构。

如果 v3 Controller 返回非 2xx（校验失败、scope 不足、限流等），JSON-RPC 回包里 isError: true 并把错误体原样带回，便于 LLM 自行决定如何处理或提示用户。

REST vs MCP，何时用哪个

适合用 REST	适合用 MCP
流程固定的工作流（定时同步、批量导入、Webhook 处理）。	终端用户用自然语言描述任务。
需要精确控制发送 / 解析的字段。	希望客户端自动发现并选择工具。
集成方不是 LLM（移动 App、ETL 管道）。	把百居易嵌进已有的 Agent（Claude / Cursor / Codex / 自研 ChatGPT 插件）。
关注吞吐，需要批量请求。	在做原型，或让运营自己用聊天驱动。

两套接口共享同一份数据和同一个 Access Token，并存使用很常见——后端跑 REST，AI 助手用 MCP。

审计

每次 MCP 工具调用都和 REST 调用同样记录——同一个 request_id、同一条 Token 维度的活动日志、同样的响应时长。确认提示是客户端侧行为（服务端保持中立，信任用户的判断）。如果你需要服务端审批工作流，请在自己侧门控该动作再调用工具。

下一步

接入客户端：MCP 快速开始 —— Claude Code / Codex / Claude Desktop / Cursor / mcp-inspector 等可直接复制粘贴的配置。
浏览目录：工具参考 —— 每个工具的参数、since-version 与示例语句。
OAuth 详情：授权流程 —— MCP 客户端 OAuth 时具体发生了什么。
整站喂给 Agent：llms.txt —— 整个站点的页面索引，便于粘进上下文或流水线。