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;DR2026 年了谁还逐字读 API 文档把 API 文档扔进浏览器让人慢慢读已经越来越不是最优解。更高效的做法是用 Scalar 基于你的 OpenAPI 文档直接生成一个 MCPModel 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 mistakesAgent 会在后台通过 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 友好且快速的回答Heres 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 MCPhttps://your-docs-domain/mcp让 AI 客户端检索、读取你已发布的文档跟随文档项目的可见性文档公开则 Docs MCP 公开否则文档内的 Ask AI 聊天无法工作Installation MCPhttps://mcp.scalar.com/mcp/YOUR_INSTALL_ID让 AI 客户端实际调用你选中的 API 端点使用你为安装installation存储的认证独立端点默认私有两者最本质的区别在于职责Docs MCP 是读文档Installation MCP 是调接口。Installation MCP 的认证规则也分两类团队成员使用 Personal Access Token个人访问令牌连接团队外人员在你授权后通过 OAuth 登录连接详见 Authentication。如果想确认某个客户端实际指向的是哪个表面可以直接curl对应 URLInstallation 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 时生成的安装 IDYOUR_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 或 OAuthAccess group访问组允许列表上的任何邮箱/域名无需 Scalar 账号OAuth 登录邮箱或 SSO面向客户与合作伙伴的私有访问想与团队之外的特定人群客户、合作伙伴共享 MCP 服务器又不想把他们邀请进工作区使用access group访问组在 Dashboard 中创建访问组添加允许的邮箱如customeracme.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 本身要求认证每个调用者使用自己的 keyScalar 不把关由你的 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。TypeScriptscalar/agentnpm i scalar/agentimport { agentScalar } from scalar/agent const scalar agentScalar({ token: your-personal-token }) const installation await scalar.installation(your-installation-id)Pythonscalar-agent可按需安装 provider 扩展pip install scalar-agent[all] # 或 [anthropic] / [openai]from scalar_agent import agent_scalar scalar agent_scalar(tokenyour-personal-token) installation scalar.installation(your-installation-id)SDK 内置了对 Vercel AI SDK、OpenAI Agents SDK、Anthropic Claude Agent SDK 的原生集成配置项仅两个token个人令牌与baseUrlMCP 服务器基础地址默认指向 Scalar 环境。计费与限流要点MCP 用量按命中哪个表面分别计量详见 Agent PricingDocs 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文档URLcreateMcptrue——即把当前 OpenAPI 文档 URL 带入注册流程一步创建 MCPOpenMCPButton.vue有配置时渲染为指向 VS Codevscode:mcp/install?...与 Cursorcursor://.../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 直接查、直接调。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考