# 已发布文档的 MCP 服务器

每个已发布的 GitBook 站点都包含一个模型上下文协议（MCP）服务器。

AI 工具可以使用它直接读取你已发布的文档。这适用于 Claude Desktop、Cursor 和 VS Code 扩展等工具。

你的 MCP 服务器位于你已发布站点的 URL 后面加上 `/~gitbook/mcp`.

例如，GitBook 的文档位于 `https://gitbook.com/docs`。它的 MCP 服务器是 `https://gitbook.com/docs/~gitbook/mcp`.

{% hint style="info" %}
如果你在浏览器中打开这个 URL，你会看到错误。请在可以发出 HTTP 请求的工具中使用它，例如 AI 助手或 IDE。
{% endhint %}

### 连接 AI 工具

{% stepper %}
{% step %}

#### 找到你的 MCP 服务器 URL

取你的已发布 GitBook 站点 URL，然后加上 `/~gitbook/mcp`.
{% endstep %}

{% step %}

#### 配置你的 AI 工具

打开你工具的 MCP 设置，然后输入服务器 URL。

每个工具的设置方式都不同。请查看你工具的文档以了解具体步骤。
{% endstep %}

{% step %}

#### 开始使用你的文档

连接后，该工具可以搜索你的文档、打开页面，并使用你的内容回答问题。
{% endstep %}
{% endstepper %}

### 要求

要使用 MCP 服务器：

* 你的站点必须已发布。MCP 服务器只公开已发布的内容。
* 你的工具必须支持通过 HTTP 的 MCP。
* 如果你的站点使用身份验证，MCP 服务器必须使用相同的访问规则。
* GitBook 仅支持 HTTP 传输。 `stdio` 和 `SSE` 不受支持。

### 将 MCP 链接添加到你的站点

在 [站点自定义](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/docs-site/customization)中，打开 [页面操作](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/docs-site/customization/extra-configuration#page-actions) 部分。然后开启 **使用 MCP 服务器连接**.

访问者随后可以从页面操作菜单中复制服务器 URL。

### 隐私和访问

MCP 服务器为你的已发布文档提供只读访问。

它绝不会暴露账户数据、分析数据或 GitBook 内部数据。

它只提供最新的已发布版本。草稿和未发布的更改会保持私密。

### 故障排查

如果工具无法连接：

* 确认你的已发布站点可访问。
* 确认 URL 以 `/~gitbook/mcp`.
* 结尾。如果站点使用身份验证，请使用支持 MCP 授权的客户端。
* 如果工具需要 `stdio` 或 `SSE`，它将无法与 GitBook 一起使用。

### 在已认证站点上使用 MCP

如果你的 GitBook 站点使用  [已认证访问](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/site-access/authenticated-access)，位于 `/~gitbook/mcp` 的 MCP 服务器会使用相同的身份验证。支持 [MCP 授权规范](https://modelcontextprotocol.io/docs/tutorials/security/authorization) 的 MCP 客户端——包括 Claude 和 Claude Code——可以使用 OAuth 和动态客户端注册（DCR）自动连接到服务器。

**工作原理**

当受支持的 MCP 客户端连接到你已认证站点的 MCP 服务器时，它会：

1. 通过 MCP 握手发现 OAuth 服务器
2. 动态注册一个 OAuth 客户端（无需手动设置 client ID）
3. 将你重定向到你站点的上游身份验证提供商进行登录
4. 将认证代码交换为访问令牌，并将其本地存储以供后续所有请求使用

GitBook 会在你首次连接时提示你进行身份验证。之后，客户端会重复使用该令牌，直到它过期。

**要求**

要使此流程生效，你的站点必须使用 GitBook 支持的以下身份验证后端之一：

* Auth0、Azure AD、Okta、AWS Cognito，或通过原生集成使用 OIDC
* 配置了回退 URL 的自定义后端

GitBook 不支持仅通过分享链接访问的站点，或使用作为静态标头传递的访客认证令牌的站点进行 MCP 身份验证。