企业官网建设流程全解析

Flue MCP深度指南：让Agent接入数千工具的开放生态

【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue

Flue MCP集成让你构建的 AI Agent 一键接入 Model Context Protocol（MCP）开放生态中的数千个工具服务——无需为 Linear、Notion、GitHub 等每个平台单独编写工具代码。本文面向新手，带你快速理解 Flue（The sandbox agent framework，沙箱 Agent 框架）如何通过一个 Hook 让 Agent 安全、可控地使用外部 MCP 工具。

什么是 MCP？为什么 Agent 需要它

MCP（Model Context Protocol，模型上下文协议）是一个开放标准，用于连接 AI Agent 与外部服务。传统做法是为每个想要的操作手写一个工具函数；而接入一个 MCP 服务器后，Agent 就能"远程"获得该服务器暴露的全部工具。

Flue 内置了完整的 MCP 客户端支持，核心实现位于运行时包 packages/runtime/src/mcp.ts，完整使用教程见官方文档 MCP 指南。

三步接入：一个 Hook 连接任意 MCP 服务器

接入方式极其简单——在你的 Agent 函数中调用useMcpConnection()即可：

'use agent'; import { useMcpConnection, useModel } from '@flue/runtime'; export function ProjectAssistant() { useModel('anthropic/claude-sonnet-4-6'); useMcpConnection({ name: 'linear', url: 'https://mcp.linear.app/mcp', auth: process.env.LINEAR_API_KEY, }); return 'Manage Linear issues and projects for the team.'; }

Agent 运行时，Flue 会自动完成三件事：

1. 连接：在 Agent 开始处理消息时建立连接，实例存活期间自动复用；
2. 发现：拉取服务器暴露的全部工具列表（支持分页发现）；
3. 挂载：把每个工具改名为mcp__<服务器>__<工具>（如mcp__linear__create_issue），避免与你自己的工具重名，模型即可像调用本地工具一样调用它们。

连接是全自动的，你无需手动打开或关闭。连接逻辑与失败重试策略（失败立即从缓存剔除、下次提交自动重试）都在 mcp.ts 中实现。

认证方式：静态 Token 还是动态凭据？

托管型 MCP 服务器通常要求 Bearer Token（标准 OAuth 2.1 授权模型），Flue 的auth字段支持两种形态：

函数形式的auth在每次请求时都会重新解析（参见 mcp-types.ts），因此 Token 过期轮换、按用户隔离凭据都能天然支持。Flue 从不存储或管理你的 Token——OAuth 流程、Token 存储与刷新逻辑由你的应用完全掌控。

用户中途完成授权后，还可以基于持久化状态条件挂载服务器：授权完成的那一刻，Agent 从下一条消息起自动获得该服务器的全部工具。

工具白名单：精准挂载，节省上下文

一个 MCP 服务器往往暴露几十个工具，而每个挂载的工具都会占用模型上下文。用tools字段声明白名单，只挂载真正需要的：

useMcpConnection({ name: 'linear', url: 'https://mcp.linear.app/mcp', auth: process.env.LINEAR_API_KEY, tools: ['create_issue', 'search_issues', 'get_issue'], });

⚠️防错设计：白名单中若写了服务器未暴露的工具名，连接会直接报错，而不是静默缩小工具集——"错名必须响亮地失败"，这在 selectMcpTools 中实现。

另外，标记为需要 task 式执行的 MCP 工具会被自动跳过并给出警告，保证 Agent 稳定运行。

一次定义，多 Agent 复用 🔄

多个 Agent 需要共用同一 MCP 服务器时，用defineMcpConnection()定义一次即可：

import { defineMcpConnection } from '@flue/runtime'; export const linear = defineMcpConnection({ name: 'linear', url: 'https://mcp.linear.app/mcp', auth: process.env.LINEAR_API_KEY, });

该函数在模块加载时就校验并冻结配置，坏配置在 import 阶段就报错，而不是等到 Agent 首次渲染。之后任何 Agent 都能直接挂载，甚至按场景覆盖字段：

useMcpConnection(linear); useMcpConnection({ ...linear, tools: ['search_issues'] }); // 局部覆盖

高级玩法：直接连接并包装工具

需要更细粒度控制时，可以下沉到createMcpConnection(definition)——它是 Hook 底层的函数：连接、发现工具，并把结果返回为普通 FlueToolDefinition。这样你可以用受信任的应用代码过滤、包装这些工具，再用useTool()挂载，例如在调用前后加审计日志。

连接定义的全部字段（传输协议streamable-http/sse、超时、请求头等）类型定义见 McpConnectionDefinition。

安全须知 🛡️

你接入的 MCP 服务器会直接影响你的 Agent：其工具描述会进入提示词，其工具结果会进入对话。Flue 官方文档给出的最佳实践：

• 把不受你控制的服务器视为第三方依赖，先审查再信任；
• 用tools白名单收窄暴露面，只开必要工具；
• 用optional: true允许服务器故障时 Agent 降级运行（不挂载该服务器工具并通知模型），避免单点故障拖垮整个 Agent。

相关资源

• 官方教程：MCP 连接指南
• MCP 连接实现：packages/runtime/src/mcp.ts
• Hook 与定义校验：packages/runtime/src/hooks/use-mcp-connection.ts
• 类型定义：packages/runtime/src/mcp-types.ts
• 项目总览：README.md

【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue