Scalar MCP + OAuth 实战：把 OpenAPI 文档变成可认证的私有 MCP 服务器-港品优选

Scalar MCP + OAuth 实战：把 OpenAPI 文档变成可认证的私有 MCP 服务器

【免费下载链接】scalarScalar is an open-source API platform: 🌐 Modern REST API Client 📖 Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar

本文基于仓库documentation/blog/2026-03-25-scalar-mcp-oauth.md与documentation/guides/agent/系列文档，结合packages/api-reference源码整理而成。文中涉及的 Dashboard 与托管服务均为 Scalar 云端能力，本文仅说明其使用与配置方式。

TL;DR：2026 年了，谁还逐字读 API 文档？

把 API 文档扔进浏览器让人慢慢读，已经越来越不是最优解。更高效的做法是：用 Scalar 基于你的 OpenAPI 文档直接生成一个 MCP（Model Context Protocol）服务器，把它分享给你的用户和团队里的 Agent。这样，任何 LLM 或 Agent 在需要调用你的 API 时，都能通过 MCP 协议实时检索到你的 API 定义与操作，而不是依赖喂进上下文里的一大坨文档。

作为演示，官方提供了一个名为Scalar Galaxy的示例 MCP 服务器（一个虚构的"星球"API），只需在终端执行一行命令即可接入：

npx add-mcp https://mcp.scalar.com/mcp/67f954ca-123c-423b-b601-7284cfac3aff

完成接入后，你可以直接向连接的客户端提问，例如：

claude, give me the curl for creating a new planet, buddy make no mistakes

Agent 会在后台通过 MCP 工具搜索 OpenAPI 中与"创建星球"匹配的操作：

⏺ Let me search the available APIs for a planet creation endpoint. ⏺ scalar-galaxy-mcp - search-openapi-operations (MCP)(question: "create a new planet")

随后返回准确、token 友好且快速的回答：

Here's your curl: curl -X POST https://galaxy.scalar.com/planets \ -H "Content-Type: application/json" \ -d '{ … }' Expects: 201 Created with the planet object (including a server-assigned id). The only required field is name — everything else is optional.

整个过程只需要"一条命令接入、一句自然语言提问"两步。这正是本篇要展开的核心主题：如何用 Scalar 从 OpenAPI 文档快速搭建 MCP 服务器，以及如何为私有 API 配置 OAuth 认证，让 Agent 安全地访问不对外公开的接口。

仓库中documentation/blog/2026-03-25-scalar-mcp-oauth.md是这篇指南的原始出处，完整的配置细节在documentation/guides/agent/mcp.md中也有更系统的梳理，可对照阅读。

Docs MCP 与 Installation MCP：两个容易混淆的入口

Scalar 暴露了两个彼此独立的 MCP 表面，大多数 MCP 客户端都把它们统称为"MCP"，因此很容易混淆：

表面	地址	能力	可见性
Docs MCP	`https://your-docs-domain/mcp`	让 AI 客户端检索、读取你已发布的文档	跟随文档项目的可见性：文档公开则 Docs MCP 公开（否则文档内的 Ask AI 聊天无法工作）
Installation MCP	`https://mcp.scalar.com/mcp/YOUR_INSTALL_ID`	让 AI 客户端实际调用你选中的 API 端点，使用你为安装（installation）存储的认证	独立端点，默认私有

两者最本质的区别在于职责：Docs MCP 是"读文档"，Installation MCP 是"调接口"。Installation MCP 的认证规则也分两类：

团队成员：使用 Personal Access Token（个人访问令牌）连接；
团队外人员：在你授权后，通过 OAuth 登录连接（详见 Authentication）。

如果想确认某个客户端实际指向的是哪个表面，可以直接curl对应 URL：Installation MCP 在缺少有效凭据时会返回401，这是它区别于 Docs MCP 的一个明确信号。

从 OpenAPI 到 MCP 服务器：三步 + 一条安装 URL

官方文档 Getting Started 将整个流程概括为三个步骤：

上传（Upload）：添加一个或多个 OpenAPI/Swagger 规范，粘贴 URL 或直接上传文件。Scalar 会解析、建立索引，并做检索与执行所需的增强处理。
配置（Configure）：创建安装（installations）、设置访问权限、预配置认证（OAuth、API Key、Bearer Token）。Agent 使用你的 Scalar 凭据，你的上游 API 密钥始终停留在执行层，不会下发给客户端。
连接（Connect）：通过 MCP URL 或 Agent SDK 接入。模型只会获得三个精简的工具，按需即时拉取 schema 与操作细节——这正是 MCP 方案"token 高效"的原因。

在 Scalar Dashboard 中创建 MCP 服务器的完整步骤：

打开 Dashboard，进入MCP；
创建一个 MCP Server；
配置你的工具（tools）：选择 API，决定暴露哪些端点；
创建一个 installation（安装）；
使用你的 API 完成认证；
记下 installation URL——之后客户端接入都要用到它。

不出 60 秒，你的 MCP Server 就绪。

连接 MCP 服务器：Personal Access Token + 安装 URL

连接客户端需要两样东西：installation URL和Personal Access Token（在 Dashboard 的Account > API Keys下创建）。

以 Claude Code 为例，在终端执行：

claude mcp add \ YOUR_MCP_SERVER_NAME \ https://mcp.scalar.com/mcp/YOUR_MCP_SERVER_ID \ --header "Authorization: YOUR_PERSONAL_ACCESS_TOKEN" \ --transport http

其中YOUR_MCP_SERVER_ID是创建 MCP Server 时生成的安装 ID，YOUR_PERSONAL_ACCESS_TOKEN是你的个人访问令牌。其他客户端的接入方式类似，具体细节以各客户端的 MCP 配置文档为准。

工具（Tools）配置：Search 与 Execute 两种模式

工具是 MCP 暴露的单个能力，每个工具对应 OpenAPI 文档中的一个操作（端点）。在 Dashboard 中进入Registry，选择你的 API，滚动到 MCP 区域并点击Configure Tools，即可配置工具。

模式	描述
Search	仅暴露端点用于检索（查找），不会向你的 API 发送任何请求
Execute	向你的 API 发起真实的、带认证的请求

Search 模式适合让 Agent 先"找到"正确的端点（正如 TL;DR 演示中search-openapi-operations所做的事），Execute 模式才真正执行调用。两者结合，既能保证 Agent 检索的准确性，又能把真实请求严格限制在你选定的端点上。

API 认证：Global 与 Passthrough 两种模式

认证按 installation 维度在 Dashboard 中配置，这让 MCP Server 可以向你的 API 发起带认证的请求，同时不把凭据暴露给客户端。

有两种模式：

Global（全局）：在 installation 上存储一个凭据（OAuth、API Key 或 Bearer Token），服务器在每次调用时都使用它。Agent 与用户永远看不到这个凭据。适合"所有人共用同一把钥匙"的场景，详见 One shared key for everyone。
Passthrough（透传）：调用方在自己指定的 header 或 query 参数中提供凭据，Scalar 每次按请求转发给上游，不落盘存储。适合"每个用户用自己的 key 调用你的 API"的场景，详见 Public MCP with passthrough auth。

一个值得注意的细节：Passthrough 模式在公开的 MCP 服务器上可以指定标准的Authorizationheader 承载凭据；但在私有的 installation 上，传入的Authorizationheader 被保留给 Scalar 的 OAuth token，因此需要改用其他 header（例如X-API-Key）。Scalar 只会转发你指定的那部分 header，结构性 header 和 Scalar 内部 header 绝不会被转发到上游。

关于"谁能连接"（公开、团队、或通过访问组 + OAuth 登录的特定客户），详见 Authentication。

私有 MCP + OAuth：让团队成员用浏览器认证

并不是所有文档都适合公开分享——无论是浏览器里的文档页面，还是 MCP 服务器本身。内部 API、即将上线的新 API、staging 环境的 API……它们都不属于公众。

解决方案很简单：把 MCP 设置为 private（私有），然后把安装 URL 分享给团队。团队成员连接时通过 OAuth 认证：

客户的 LLM 会打开一个浏览器窗口；
用户在窗口中用 Scalar 认证（前提是他们在你的团队里）；
认证成功后，客户端获得访问权，即可调用你的私有 API。

这正是本文标题中 "OAuth" 的关键场景：URL 本身不会泄漏访问权——一个没有 OAuth 登录资格的 URL，对任何人都毫无用处。

双层认证模型：先管"谁能连"，再管"怎么调"

理解私有 MCP 的 OAuth 机制，需要先分清 MCP 服务器的两个独立认证层：

谁被允许连接 MCP 服务器？这是 Scalar 侧的访问控制——公开、你的团队、或某个访问组。
服务器如何调用你的上游 API？这是按 installation 配置的上游认证——要么存储一个凭据，要么由调用方透传凭据。

两者相互独立：某人可以被允许连接（第一层），同时服务器可以用你存储的 key——或者用调用方自己提供的 key（第二层）——去调用你的 API。

谁能连接：Public / Team / Access group 三种方式

每个 installation默认私有。调用方获得访问权限的方式有三种：

访问方式	谁能进来	如何认证
Public（公开）	任何拥有 URL 的人	无需 Scalar 认证
Team（团队）	安装所属团队的成员	Personal Access Token 或 OAuth
Access group（访问组）	允许列表上的任何邮箱/域名（无需 Scalar 账号）	OAuth 登录（邮箱或 SSO）

面向客户与合作伙伴的私有访问

想与团队之外的特定人群（客户、合作伙伴）共享 MCP 服务器，又不想把他们邀请进工作区？使用access group（访问组）：

在 Dashboard 中创建访问组，添加允许的邮箱（如customer@acme.com）或整个域名（如acme.com）；
打开 MCP installation，把访问组挂上去；
把安装 URL 分享给这些用户。

外部用户连接时走标准 OAuth 流程：

MCP 客户端打开浏览器，跳到该 installation 的 Scalar 登录页；
用户用**邮箱（一次性验证码）**或SSO登录（前提是团队配置了身份提供方）；
Scalar 校验该邮箱是否匹配 installation 的访问组；
校验通过后，客户端收到 OAuth token 并连接。用户不会获得任何 Dashboard 访问权限——只有 MCP 服务器的访问权。

登录页上显示邮箱登录还是 SSO 选项，由团队的外部访问设置控制。如果团队关闭了邮箱登录且未配置身份提供方，登录页将没有任何可用的登录方式——请确保至少启用一种。

访问组机制也带来了灵活性：一个 installation 可以挂多个访问组，一个访问组也可以复用在多个 installation 上。判断"用户是否被允许"，就看其认证邮箱是否命中访问组的邮箱/域名列表。

登录门户（Login Portal）：把登录页换成你的品牌

登录门户可以把 OAuth 登录页定制成你的产品样式，而不是通用的 Scalar 页面。可以设置：标题与描述、公司名称与 Logo、favicon、主题、指向你的条款与隐私政策的链接。

在 Dashboard 中创建登录门户并设置品牌信息；
把它挂到 installation 上。

注意：门户只改变登录页的外观与文案，不改变准入规则——准入依然完全由 installation 的访问组决定。如果门户看起来"没生效"，请检查：installation 是否为私有、是否挂了访问组、团队是否启用了至少一种登录方式（邮箱或 SSO）。

面向多客户共享：三种组合配方

把上面两层认证组合起来，绝大多数场景都能套进以下三种配方之一：

配方	适用场景	说明
公开 MCP + 透传认证	API 本身要求认证，每个调用者使用自己的 key	Scalar 不把关，由你的 API 把关；最简单地向全世界共享一个 MCP。详见 Public MCP with passthrough auth
面向客户的私有访问	只把服务器开放给指定邮箱/域名（客户、合作伙伴）	用访问组 + OAuth 登录把关，并给登录页换品牌。详见 Private access for customers
共享一把钥匙	所有调用方使用同一凭据	在 installation 上存储单个凭据，调用方永远不接触 key。详见 One shared key for everyone

其中"面向客户"的场景还提供两种精细化策略：

每个客户有自己的 API key：访问组 + 透传认证，一个 installation、一个 URL，每个客户带自己的 key 接入，同时用访问组把连接限制在客户邮箱范围内；
希望客户永不接触 key：全局认证 + 每个客户一个 installation，各自存储该客户的 key，并挂上按客户划分的访问组。installation 和访问组都可以通过 Scalar API 编程创建，因此可以按客户脚本化批量配置，而无需在 Dashboard 里逐个点击。

当前已知限制

MCP 服务器暂不支持自定义域名：installation 只能从 Scalar 的 MCP 端点按 installation ID 提供服务，无法从你自己的域名（如mcp.yourcompany.com）提供 MCP 服务。自定义域名目前仅支持托管文档，不支持 Installation MCP。
单个共享 URL 尚不能按登录用户注入不同的存储 key：要让每个用户拥有自己的 key，目前只能使用透传（用户自带 key）或每用户一个 installation。完全动态的按用户 installation 已在路线图上。

Agent SDK：在代码里接入 MCP（可选深化）

除了通过claude mcp add等客户端命令接入，Scalar 还提供Python 与 TypeScript 两种 Agent SDK，方便在自有 Agent 运行时中以代码方式接入同一个 OpenAPI MCP 服务器（详见 Agent SDK）。

TypeScript（@scalar/agent）：

npm i @scalar/agent

import { agentScalar } from '@scalar/agent' const scalar = agentScalar({ token: 'your-personal-token' }) const installation = await scalar.installation('your-installation-id')

Python（scalar-agent，可按需安装 provider 扩展）：

pip install "scalar-agent[all]" # 或 [anthropic] / [openai]

from scalar_agent import agent_scalar scalar = agent_scalar(token="your-personal-token") installation = scalar.installation("your-installation-id")

SDK 内置了对 Vercel AI SDK、OpenAI Agents SDK、Anthropic Claude Agent SDK 的原生集成，配置项仅两个：token（个人令牌）与baseUrl（MCP 服务器基础地址，默认指向 Scalar 环境）。

计费与限流要点

MCP 用量按命中哪个表面分别计量（详见 Agent Pricing）：

Docs MCP：查询按 Agent messages 计费，与文档内 Ask AI 小组件同价；用量明细可在 Dashboard 的计费页面查看。
Installation MCP：目前不计费。一个统一 docs chat、API chat 与 MCP 工具计费的 credits 体系正在推进中。

限流方面，Docs MCP 只要文档项目公开就对外可达，因此在负载均衡器层做了限流以防范滥用；这些限制目前不能按项目单独配置。如果有特殊需求（例如预期流量尖峰或更严格的上限），需要联系团队协调设置。

源码印证：UI 中的 MCP 入口是怎么工作的

仓库packages/api-reference中，OpenMCPButton.vue 实现了 API 参考页面中的 MCP 连接入口，其行为与本文描述的"公开分享/私有连接"流程完全对应，可以作为理解 UI 侧实现的第一手资料：

无配置时：渲染为按钮（Generate MCP，对应本地化文案见 en.ts），点击后通过generateRegisterLink()打开 Dashboard 的注册页：${dashboardUrl}/register?url=<文档URL>&createMcp=true——即把当前 OpenAPI 文档 URL 带入注册流程，一步创建 MCP（OpenMCPButton.vue）；
有配置时：渲染为指向 VS Code（vscode:mcp/install?...）与 Cursor（cursor://.../mcp/install?...）的深链，点击直达客户端安装页；"Connect MCP" 则把配置中的 URL 复制到剪贴板（OpenMCPButton.vue）。

对应的端到端测试 mcp-button.e2e.ts 验证了三种状态：默认显示 "Generate MCP"、配置了mcp.name与mcp.url后显示 "Connect MCP"、mcp.disabled: true时隐藏 MCP 入口。如果你想在自己的 API 参考文档中接入 MCP 按钮，配置项就是mcp: { name, url, disabled }这个结构。

结语

从一条npx add-mcp命令，到私有 installation 上的 OAuth 认证，Scalar 把"OpenAPI 文档 → Agent 可调用的 MCP 服务器"这条路压缩到了分钟级：公开 API 直接分享 URL，私有 API 用访问组 + OAuth 把关，每个调用方按需选择 Global 或 Passthrough 认证。对团队和客户而言，文档与 API 的消费方式，正在从"人读文档"走向"Agent 直接查、直接调"。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析