Scalar Agent 实战解析用 3 个 MCP 工具、0.2% 的上下文开销让 AI Agent 稳定调用任意 API【免费下载链接】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 Agent 与真实 API 连接起来简单又好玩但当 API 定义体量变大时事情就完全不同了把整份 OpenAPI 文档塞进 prompt上下文窗口瞬间被击穿Agent 开始凭空捏造不存在的 endpoint。本文以 Scalar 开源的 API 平台为背景剖析其新一代产品Agent如何把工具面tool surface收敛到固定 3 个、按需拉取 schema从而将上下文开销压到约 0.2%并给出可直接落地的 Chat UI 与 Agent SDK 接入方案。问题的本质raw OpenAPI 是 Agent 的最坏工作量Agent 调用 API 最朴素的做法是把完整的 OpenAPI 文档直接丢进 prompt。Scalar 团队在 2026-03-05-agent-scalar.md 中直白地总结了尝试结果模型还没开始干活上下文窗口就已经爆掉随之而来的是幻构的 endpoint 与不可靠的响应。以真实服务为例Zoom Meetings API完整 OpenAPI 文档体量巨大直接放入 prompt 后模型在动手前就已突破上下文上限Notion API相对更小但 raw OpenAPI 依然昂贵——它能跑通但每一次运行都要支付高昂的 token 税。MCPModel Context Protocol能缓解一部分问题把 API 包装成 MCP 工具即可接入这是很多团队的默认选择。但 MCP 并非免费午餐——原生 MCP 对每个 endpoint 都会携带 schema token。一个拥有上百个 endpoint 的 API仅仅工具清单 完整 schema就会吃掉大量上下文。Agent 的解法是把整个 API 折叠成 3 个工具只按需拉取当前操作需要的 schema。Agent 的核心思路固定 3 工具 按需取数Agent 通过 MCP 暴露给模型三个工具覆盖任何 API 的全部操作工具职责summarize-openapi-specs返回 spec 与可用 endpoint 的简短摘要search-openapi-operations按用户搜索返回匹配 endpoint 的迷你化OpenAPI 文档execute-request实际发起请求执行三个工具各司其职模型先看摘要建立全局认知再针对具体需求检索对应的迷你 schema最后执行请求。操作细节是在需要时才被检索而不是在第一轮对话中就全部倾倒给模型。结果是更小的上下文、更少的步骤、更准确的工具调用路由。基准测试三种方案的真实对比为了验证效果Scalar 用真实 API 跑了对照基准三个方案执行完全相同的任务Raw OpenAPI把原始 OpenAPI 文档放进 promptNative MCP原生 MCP 服务器一个 endpoint 对应一个工具AgentScalar Agent固定 3 个工具summarize、search、execute。测试对象为Zoom Meetings APIlist / create / update与Notion APIsearch / create page / get workspaceNotion 示例 prompt 与 Notion 官方 MCP 工具指南对齐token 统计使用 tiktoken 完成。Schema Cost 表格基于 200k 上下文窗口计算。Zoom Meetings任务执行汇总ModeTaskRunsSuccessAvg TokensAvg LatencyAvg Stepsraw-openapiList upcoming meetings10%3857972205 ms0.0native-mcpList upcoming meetings1100%2017947887 ms6.0agent-scalarList upcoming meetings1100%553123029 ms2.0raw-openapiCreate a meeting10%3857912011 ms0.0native-mcpCreate a meeting1100%9547446529 ms6.0agent-scalarCreate a meeting1100%3932720637 ms2.0raw-openapiUpdate a meeting10%3857921978 ms0.0native-mcpUpdate a meeting1100%9540645189 ms6.0agent-scalarUpdate a meeting1100%1267413367 ms2.0Schema 成本200k 上下文ApproachToolsToken costSchema TokensAll-in TokensContext used (200k)Raw OpenAPI Spec in prompt--2956560295656147.8%Native MCP (full schemas)183892818953017881189.4%Native MCP (required params only)1835504895309503447.5%Agent (MCP tools)34124124120.2%Notion任务执行汇总ModeTaskRunsSuccessAvg TokensAvg LatencyAvg Stepsraw-openapiSearch for budget approval docs1100%95819114858 ms1.0native-mcpSearch for budget approval docs1100%1472539663 ms6.0agent-scalarSearch for budget approval docs1100%187351474 ms3.0raw-openapiCreate project kickoff page1100%9647975803 ms1.0native-mcpCreate project kickoff page1100%1464351163 ms6.0agent-scalarCreate project kickoff page1100%1454103488 ms2.0raw-openapiWhich workspace am I connected to?1100%9549022175 ms1.0native-mcpWhich workspace am I connected to?1100%1438527013 ms6.0agent-scalarWhich workspace am I connected to?1100%120627580 ms3.0Schema 成本200k 上下文ApproachToolsToken costSchema TokensAll-in TokensContext used (200k)Raw OpenAPI Spec in prompt--6911406911434.6%Native MCP (full schemas)26210412803149077.5%Native MCP (required params only)2682912803136326.8%Agent (MCP tools)34004004000.2%结果分析Agent 为什么能赢两组基准的结论高度一致Agent 以约 0.2% 的上下文占用成为明显赢家原因可以归结为三点原生 MCP 随 endpoint 数量线性膨胀Agent 不会。无论 API 有多少 endpointAgent 始终只有 3 个工具覆盖全部操作不做全量预加载。Agent 不在一开始加载完整 API 定义而是先调用一个迷你版本只包含当前任务所需的 endpoint 与 schemaschema 足迹极小。即便是 Zoom Meetings API 这种大型 APIschema 也只有几百 token 量级对比完整 OpenAPI 需要 29 万 token。从执行质量看raw-openapi 模式在 Zoom 测试中成功率 0%上下文溢出导致无法完成而 Agent 在全部任务上 100% 成功且平均步骤数稳定在 23 步显著低于原生 MCP 的 6 步——工具面收敛直接带来了更精准的路由。工作原理三步把 OpenAPI 变成 Agent 可用的 MCPAgent 的底层链路非常简单与 getting-started.md 描述的流程完全一致上传Upload把 OpenAPI 文档上传到 Scalar粘贴 URL 或直接上传Scalar 负责解析、索引并为其增强搜索与执行能力配置Configure创建 MCP 安装installation、设置访问权限、预配置认证OAuth、API key、bearer token。Agent 使用你的 Scalar 凭据发起请求上游 API 密钥始终留在 Scalar 的执行层不会泄露给客户端连接Connect通过 MCP URL 或 Agent SDK 接入。模型获得三个精简工具按需拉取 schema 与操作细节。从源码结构看Scalar 仓库中对应的 Agent 能力被组织在 documentation/guides/agent 目录下包含 MCP 服务器说明、Agent SDK 说明、认证方案 与 API Reference 集成 等完整文档体系。上手方式一Chat UI零代码体验最简单的方式是直接把 OpenAPI 文档上传到agent.scalar.com的聊天界面即可与自己的 API 对话。这一方式适合快速验证不写一行代码就能观察 Agent 如何检索 schema 并执行请求。上手方式二Agent SDK接入自有 Agent 运行时如果你有自己的 Agent 运行时可以连接 Scalar 的 MCP 服务器。Scalar 提供 TypeScript 与 Python 两套 SDKTypeScriptscalar/agent原生支持 Vercel AI SDK、OpenAI Agents SDK、Anthropic Claude Agent SDKPythonscalar-agent支持 OpenAI Agents SDK 与 Anthropic Claude Agent SDK。TypeScriptOpenAI Agents SDK示例原博客文档给出了一个完整可运行的接入示例import { Agent, MCPServerStreamableHttp, run } from openai/agents import { agentScalar } from scalar-org/agent-sdk const scalar agentScalar({ agentKey: YOUR_AGENT_KEY, }) const session await scalar.session() const serverOptions session.createOpenAIMCPServerOptions() const servers serverOptions.map((opts) new MCPServerStreamableHttp(opts)) await Promise.all(servers.map((s) s.connect())) const agent new Agent({ name: api-agent, instructions: You help users interact with APIs., mcpServers: servers, }) const result await run(agent, pls list available endpoints in the zoom api thanks) await Promise.all(servers.map((s) s.close()))安装方式npm i scalar/agent个人访问令牌在 Scalar Dashboard 的Account API Keys下创建。SDK 的配置项包括token用于认证 MCP 请求的个人令牌与可选的baseUrlScalar MCP 服务器地址默认指向 Scalar 环境详见 sdk.md。PythonOpenAI Agents SDK示例import asyncio from scalar_agent import agent_scalar from agents import Agent, Runner from agents.mcp import MCPServerStreamableHttp async def main() - None: scalar agent_scalar(tokenyour-personal-token) installation scalar.installation(your-installation-id) server MCPServerStreamableHttp(**installation.create_openai_mcp()) await server.connect() agent Agent(nameapi-agent, mcp_servers[server]) result await Runner.run(agent, Which APIs are available that let me create a planet?) print(result.final_output) await server.cleanup() asyncio.run(main())安装方式pip install scalar-agent按 provider 可加装scalar-agent[anthropic]、scalar-agent[openai]或scalar-agent[all]。Agent 能够横跨N 个 API进行扩展无论你的 Agent 需要访问多少 API都不会淹没上下文窗口同时保持最高的工具调用准确率。进阶理解 Docs MCP 与 Installation MCP在配置 MCP 时需要区分 Scalar 暴露的两套 MCP 表面详见 mcp.mdDocs MCP位于https://your-docs-domain/mcp让 AI 客户端搜索和阅读你已发布的文档代理经过文档托管继承文档项目的可见性Installation MCP位于https://mcp.scalar.com/mcp/YOUR_INSTALL_ID让 AI 客户端调用你选定的 API endpoint使用安装时存储的认证信息。它默认私有团队成员用个人访问令牌连接团队外成员通过 OAuth 登录后被授权访问。创建 MCP 服务器只需在 Scalar Dashboard 的MCP页面新建服务器、配置工具、选择要暴露的 endpoint、创建安装并完成 API 认证。每个工具对应 OpenAPI 文档中的一个操作endpoint并可在 Dashboard 的Registry → 你的 API → MCP → Configure Tools中按两种模式配置模式说明Search仅暴露该 endpoint 用于查找不向你的 API 发起请求Execute向你的 API 发起真实、经过认证的请求用 Claude Code 连接 Installation MCP 的命令示例claude mcp add \ YOUR_MCP_SERVER_NAME \ https://mcp.scalar.com/mcp/YOUR_MCP_SERVER_ID \ --header Authorization: YOUR_PERSONAL_ACCESS_TOKEN \ --transport http安全模型两层独立认证MCP 服务器存在两层彼此独立的认证详见 authentication/index.md谁能连接 MCP 服务器Scalar 侧的访问控制——默认私有可通过三种方式授权Public任何人持 URL 即可访问无需 Scalar 认证、Team安装所属团队成员使用个人访问令牌或 OAuth、Access group允许名单上的邮箱/域名通过 OAuth 登录服务器如何调用你的上游 API按安装配置的上游认证——Global模式在安装上存储一份凭据供每次调用使用Agent 永远看不到它Passthrough模式由调用方提供凭据、Scalar 逐请求转发而不存储。两层彼此独立某用户可能被允许连接第 1 层而服务器用你存储的密钥第 2 层 Global或用户自带的密钥第 2 层 Passthrough调用你的 API。这也解释了文章开头的安全承诺Agent 永远不会拿到你的上游 API 凭据。延伸Agent 也内嵌在 API Reference 中除了 MCP 连接Agent 还能驱动 Scalar API Reference 内嵌的聊天控件参考 UI 中的 sparkle 图标。该流程使用来自 Registry 的Agent key与 MCP installation 相互独立详见 api-reference.md本地开发在http://localhost上默认启用每个会话 10 条免费消息无需任何配置生产部署需要 Agent key未配置 key 时聊天控件不显示。key 在 Dashboard 的 Registry 中按具体 OpenAPI 文档创建可通过 GitHub Actions 自动同步文档确保 Agent 始终使用最新 API 信息配置参考agent配置项支持keyAgent key、disabled布尔值全局关闭 Agent、hideAddApi隐藏添加 API控件仅展示预加载的 API并支持按sources逐源配置。Scalar.createApiReference(#app, { sources: [ { url: https://registry.scalar.com/your-namespace/apis/your-api/latest?formatjson, agent: { key: your-agent-scalar-key, }, }, ], })总结Scalar Agent 给出了一个反直觉但极其有效的设计与其让 Agent 提前掌握 API 的全部细节不如给它一个稳定的三工具接口按需拉取 schema。基准测试表明相比 raw OpenAPIZoom 场景下 147.8% 的 200k 上下文占用和原生 MCP89.4%Agent 将上下文占用压缩到 0.2%同时保持 100% 的任务成功率与更少的推理步骤。无论你的 API 目录只有一个 spec 还是横跨数百个微服务这套固定工具面 按需取数 安全委托认证的架构都能让 Agent 以最小成本、最高准确率接入你的 API。【免费下载链接】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），仅供参考
