Klavis MCP 集成平台技术解析：Strata 智能路由、100+ MCP 服务器与可训练沙箱环境

Klavis MCP 集成平台技术解析：Strata 智能路由、100+ MCP 服务器与可训练沙箱环境

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis

Klavis AI 是一个面向 AI Agent 的 MCP（Model Context Protocol）集成平台，目标是让 LLM 能够以可靠的、可扩展的方式调用各类真实世界的工具。本文基于仓库根目录 README.md 的主体结构展开，覆盖平台的三条产品线（Strata、MCP Integrations、MCP Sandbox）、四种接入方式（云托管、自托管、SDK、REST API），并结合仓库中的开源 Strata 实现（open-strata/）、100+ MCP 服务器源码（mcp_servers/）与集成示例（examples/）给出可落地的实操路径与源码级证据。读完后你可以：独立搭建一个本地 Strata MCP 路由器、通过 Docker 自托管任意 Klavis MCP 服务器、用 Python/TypeScript SDK 创建云端 Strata 实例，并理解沙箱环境在 LLM 训练/RL 场景中的生命周期。

一、平台总览：三条产品线

根 README.md 以 "Choose Your Solution" 开篇，将整个平台划分为三个互补的解决方案：

1.1 Strata：用"渐进式工具发现"替代"工具洪水"

根据 docs/concepts/strata.mdx 的官方定义，Strata 是"一个让 AI Agent 以任意复杂度可靠使用工具的 MCP 服务器"。它针对当前 Agent 的三大痛点设计：

• 工具过载（Tool Overload）：工具数量过多导致 LLM 选择困难；
• 上下文过载（Context Overload）：冗长的工具列表推高 token 成本；
• 覆盖缺口（Coverage Gap）：多数服务器停留在 40~50 个工具，限制了可构建的上限。

Strata 的解决思路是渐进式暴露（progressive tool discovery）：不把数百个工具一次性灌给模型，而是只暴露少量"元工具"，由 Agent 按需逐层下钻。官方文档与开源实现共同确认了这套工具集。在开源实现 open-strata/src/strata/tools.py 中，工具名以常量形式集中定义：

# open-strata/src/strata/tools.py TOOL_DISCOVER_SERVER_ACTIONS = "discover_server_actions" TOOL_GET_ACTION_DETAILS = "get_action_details" TOOL_EXECUTE_ACTION = "execute_action" TOOL_SEARCH_DOCUMENTATION = "search_documentation" TOOL_HANDLE_AUTH_FAILURE = "handle_auth_failure"

而get_tool_definitions()为每个工具生成了带inputSchema的 MCPTool对象，其中discover_server_actions被明确标注为 "PREFERRED STARTING POINT"（首选入口点），其server_names参数的enum会动态填充为当前用户可用的服务器列表——这就是"智能路由"在源码层面的体现：模型看到的候选服务器范围由配置决定，而非全量工具。

完整的服务端工具集（见 docs/concepts/strata.mdx）还包括：

注意execute_action的两个"上下文优化"参数：include_output_fields允许 Agent 只取需要的字段路径（如author.displayName），maximum_output_characters则是对响应长度的硬截断——二者直接服务于"控制回注模型的 token 量"这一核心目标。

1.2 MCP Integrations：100+ 预构建服务器

mcp_servers/ 目录是集成产品的主体：每个子目录对应一个独立 MCP 服务器（github/、gmail/、slack/、notion/、google_sheets/、postgres/、salesforce/等，按文件树统计超过 100 个），技术栈覆盖 Python（server.py+tools/工具模块）、TypeScript、Go（如 mcp_servers/github/pkg/ 中的 Go 实现），每个服务器自带 Dockerfile 与 README。子目录的 mcp_servers/README.md 给出了自托管与托管服务两种用法，详见下文"自托管"章节。

1.3 MCP Sandbox：面向训练与 RL 的可重置环境

根据 docs/concepts/sandbox.mdx，Sandbox 面向 LLM 研究者构建真实工具使用的训练/强化学习环境，解决五类痛点：管理环境与测试账号、实现 MCP 服务器与处理认证、初始化真实数据、多次运行间重置状态、并发会话间的隔离。其生命周期分为五步：

1. Create：按所需外部服务（Snowflake、GitHub、Notion、Woocommerce 等）请求一个隔离沙箱，获得该实例的 MCP 服务器 URL；
2. Initialize：以 JSON 或 API 方式加载确定性的"世界状态"，平台负责建库、灌数；
3. Interact via MCP：让 Agent 像操作真实应用一样通过 MCP 工具操作沙箱，可同时挂多个服务器；
4. Verify：读取完整沙箱状态，与 ground truth 程序化比对以判定任务是否完成；
5. Reset / Delete：清除沙箱回到干净状态，开启下一轮。

文档明确该沙箱基础设施是横向可扩展的。配套示例见 examples/klavis-sandbox/ 目录下的系列 Notebook（klavis_sandbox.ipynb、klavis_local_sandbox.ipynb、klavis_gmail_mcp_sandbox.ipynb等）。

二、快速上手：README 中的四种接入路径

根 README.md 的 Quick Start 章节给出四条并列路径，下面逐条展开并结合仓库证据补全细节。

2.1 Option 1：云托管（klavis.ai）

官方文档入口在 docs/quickstart.mdx，其 UI 路径为三步：

1. 打开 Dashboard：Klavis 默认为你启用所有集成，可用省略号按钮单独禁用某个集成；
2. Authenticate：点击 "Authorize" 走 OAuth 流程（多数应用支持 OAuth，部分需要 API key，个别无需认证）；
3. 在应用中使用：点击 "Add to Other Clients" 获取 MCP 服务器 URL 与访问令牌，接入 Cursor、Claude Code、VS Code、ChatGPT 等任意 MCP 客户端。

文档特别提示：带 access token 的 URL 与直连 URL 提供的是同一个MCP 服务，但推荐前者（更安全），且切勿公开分享access token 或直连 URL，因为它们可访问你已连接的账号与数据。

2.2 Option 2：自托管

根 README 给出两条自托管命令：

# 运行任意 MCP Integration（以 GitHub 为例） docker pull ghcr.io/klavis-ai/github-mcp-server:latest docker run -p 5000:5000 ghcr.io/klavis-ai/github-mcp-server:latest # 本地安装开源 Strata pipx install strata-mcp strata add --type stdio playwright npx @playwright/mcp@latest

mcp_servers/README.md 补充了完整细节：

• MCP 服务器在5000 端口运行，MCP 协议暴露在/mcp路径；
• OAuth 类服务器可通过环境变量KLAVIS_API_KEY启用托管 OAuth（平台代管 OAuth 流程），或手动注入凭据：-e AUTH_DATA='{"access_token":"ghp_xxx"}'；
• 客户端配置示例（以 Cursor 为例）：

{ "mcpServers": { "github": { "url": "http://localhost:5000/mcp/" } } }

• Docker 镜像命名规范：ghcr.io/klavis-ai/{server-name}-mcp-server:latest（支持按 commit-id 取版本）；
• 除 Docker 外还支持从源码构建：Go 服务器go run server.go、Python 服务器pip install -r requirements.txt && python server.py、Node.js 服务器npm install && npm start（以 mcp_servers/github/、mcp_servers/youtube/ 等各自的 README 为准）。

开源 Strata 的完整自托管流程见 open-strata/README.md：

# 安装 pipx install strata-mcp # 或 pip install strata-mcp pip install -e . # 开发模式（源码构建） # 添加服务器（四种传输类型） strata add --type stdio <server_name> npx @playwright/mcp@latest strata add --type sse <server_name> http://localhost:8080/mcp/ --env API_KEY=your_key strata add --type http <server_name> https://api.githubcopilot.com/mcp/ --header "Authorization=Bearer token" strata add --type http <server_name> https://mcp.notion.com/mcp --auth_type oauth # 管理服务器 strata list strata enable <server_name> strata disable <server_name> strata remove <server_name> # 运行 Strata 自身（它本身就是一个 MCP 服务器） strata # stdio 模式（默认），等价于 python -m strata strata run --port 8080 # HTTP/SSE 服务模式 # 一键写入 AI 客户端配置 strata tool add claude # 支持 --scope project strata tool add gemini strata tool add vscode strata tool add cursor --scope user

配置文件默认保存在~/.config/strata/servers.json（该路径可由 open-strata/src/strata/config.py 确认：config_path为config_dir / "servers.json"），也支持--config-path覆盖。配置格式兼容通用 MCP JSON 结构：

{ "mcp": { "servers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "your_token" }, "enabled": true }, "api-server": { "type": "http", "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer token" }, "enabled": true } } } }

从源码结构看（open-strata/src/strata/config.py），非 stdio 类型会在解析时自动补写type字段，stdio 为默认类型，与上述配置中github条目无type字段的行为一致。相关环境变量：

• MCP_CONFIG_PATH：自定义配置文件路径；
• MCP_ROUTER_PORT：HTTP/SSE 模式默认端口（默认 8080）。

源码结构方面，open-strata/src/strata/ 包含cli.py（命令行）、server.py（stdio/HTTP/SSE 服务器实现）、tools.py（工具定义与实现）、mcp_client_manager.py（下游 MCP 客户端管理）、config.py（配置管理）、mcp_proxy/（代理层）等模块，入口为 open-strata/src/strata/main.py（python -m strata调用）。测试通过pytest运行，测试用例位于 open-strata/tests/。

2.3 Option 3：SDK

根 README 给出 Python 与 TypeScript 两种 SDK 用法，注意区分Strata 实例（聚合多服务器）与单服务器实例两种模式：

# Python SDK from klavis import Klavis from klavis.types import McpServerName klavis = Klavis(api_key="your-key") # 创建 Strata 实例（聚合 Gmail + Slack） strata = klavis_client.mcp_server.create_strata_server( user_id="user123", servers=[McpServerName.GMAIL, McpServerName.SLACK], ) # 或创建单个 MCP 服务器实例 gmail = klavis.mcp_server.create_server_instance( server_name=McpServerName.GMAIL, user_id="user123", )

// TypeScript SDK import { KlavisClient, McpServerName } from 'klavis'; const klavis = new KlavisClient({ apiKey: 'your-api-key' }); // 创建 Strata 实例 const strata = await klavis.mcpServer.createStrataServer({ userId: "user123", servers: [Klavis.McpServerName.Gmail, Klavis.McpServerName.Slack], }); // 或创建单个 MCP 服务器实例 const gmail = await klavis.mcpServer.createServerInstance({ serverName: McpServerName.GMAIL, userId: "user123" });

docs/quickstart.mdx 对 SDK 路径做了更细致的说明：安装命令为pip install klavis/npm install klavis；userId标识"你在 Klavis 中访问的是谁的已连接账号与数据"，应为你自己、团队或组织分配的唯一 ID。API 的响应包含三类关键信息：

• strataServerUrl：MCP 客户端连接 Strata 服务器使用的 URL；
• oauthUrls：需要 OAuth 认证的服务对应的授权链接；
• apiKeyUrls：使用 API key 认证的服务对应的配置链接。

SDK 的框架级集成示例可参考 examples/ 目录：examples/langchain-klavis/、examples/llamaindex-klavis/、examples/crewai-klavis/、examples/openai-klavis/、examples/google_gemini_cli-klavis/等均提供 Python/TypeScript 双版本代码。以 LangChain 集成（docs/quickstart.mdx 中给出的完整流程）为例，其核心链路为：创建 Strata 服务器 → 处理 OAuth → 用MultiServerMCPClient以streamable_http传输连接response.strata_server_url并get_tools()→ 交给create_react_agent执行。LlamaIndex 版本则使用BasicMCPClient+aget_tools_from_mcp_url，AutoGen 版本使用StreamableHttpServerParams（timeout=30.0、sse_read_timeout=300.0）+mcp_server_tools。

2.4 Option 4：REST API

根 README 给出两个核心 REST 端点的 curl 示例：

# 创建 Strata 服务器 curl -X POST "https://api.klavis.ai/v1/mcp-server/strata" \ -H "Authorization: Bearer your-api-key" \ -H "Content-Type: application/json" \ -d '{ "user_id": "user123", "servers": ["GMAIL", "SLACK"] }' # 创建单个 MCP 服务器 curl -X POST "https://api.klavis.ai/v1/mcp-server/instance" \ -H "Authorization: Bearer your-api-key" \ -H "Content-Type: application/json" \ -d '{ "server_name": "GMAIL", "user_id": "user123" }'

说明：docs/quickstart.mdx 中的 curl 示例使用/mcp-server/strata/create路径并采用 camelCase 请求体（userId、servers: ["Gmail", "YouTube"]），与根 README 的/v1/mcp-server/strata+ snake_case 略有差异，实际使用时以 docs/api-reference/ 下的 API 参考文档与 openapi.json 为准。完整的 REST 端点与 schema 参考位于 docs/api-reference/strata/ 目录。

三、仓库结构导读

结合根 README 的三大板块，仓库各目录与文档的对应关系如下，方便按图索骥：

四、选型建议与适用前提

基于文档与源码可以给出如下选择依据：

• 想让自己的 Agent 一次性接入大量工具且不污染上下文→ 优先 Strata：云端版（Dashboard/API/SDK）或开源版（pipx install strata-mcp，本地配置，数据不出内网）。开源版暴露的元工具集为 5 个（open-strata/src/strata/tools.py 中的常量），服务端版额外提供discover_server_categories_or_actions与get_category_actions等类别层级工具（见 docs/concepts/strata.mdx），即服务端版支持更细的渐进下钻粒度；
• 只需要某一个 SaaS/数据库的 MCP 接入，且要自托管→ 直接使用 mcp_servers/ 下对应目录的 Docker 镜像（端口 5000、路径/mcp），OAuth 服务器注入KLAVIS_API_KEY走托管 OAuth，或手动注入AUTH_DATA；
• 做 LLM 训练、评测或 RL→ MCP Sandbox（生命周期见 docs/concepts/sandbox.mdx），参考 examples/klavis-sandbox/ 的 Notebook 完成"创建 → 灌数 → Agent 交互 → 校验 → 重置"闭环；
• 需要 API 与工具的一一对应（而非 Strata 聚合）→ 使用 MCP Server Instance 端点（对应 docs/legacy/instance.mdx 的 1:1 映射模式）。

适用前提提示：SDK/REST 路径依赖有效的 Klavis API key 与平台服务；开源 Strata 的默认端口为 8080（MCP_ROUTER_PORT），配置文件默认位于~/.config/strata/servers.json；所有自托管命令均以仓库当前版本（各服务器 README 与 Dockerfile）为准，具体服务的认证要求见各mcp_servers/<name>/README.md。

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis