跳转到内容
Flue

输入关键词开始搜索文档。

MCP

最后更新 查看 Markdown 源文件

MCP（模型上下文协议）是一个将 AI 智能体连接到外部服务的开放标准。无需为你智能体需要的每个 Linear、Notion 或 GitHub 操作编写工具，只需连接到 MCP 服务器，你的智能体就能远程访问其工具。

本指南涵盖如何使用 useMcpConnection() 连接到服务器、管理认证和配置连接。

连接到 MCP 服务器

通过在你的智能体内调用 useMcpConnection() 来连接到 MCP 服务器：

src/agents/project-assistant.ts
'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 '为团队管理 Linear 问题和项目。';
}

当智能体运行时，Flue 连接到服务器，发现其工具，并将它们添加到智能体的工具集中。工具命名为 mcp__<server>__<tool>（此处为 mcp__linear__create_issue）以避免与你自己的工具冲突，模型像调用其他任何工具一样调用它们。

连接的行为方式：

  • 当智能体开始处理消息时 Flue 进行连接，并在实例存活期间复用连接。你无需自己打开或关闭连接。
  • 如果服务器无法访问，运行会以错误失败，下一条消息会重试。在定义上设置 optional: true 可以在没有该服务器工具的情况下运行；模型会被告知它们不可用。
  • 声明可以是有条件的，就像工具挂载一样：智能体可以基于其状态获得或失去一个服务器，模型会被告知这个变化。

参见 useMcpConnection 参考 了解行为的更多详情。

向 MCP 服务器认证

许多托管的 MCP 服务器期望一个 Bearer 令牌，遵循 MCP 授权模型（标准 OAuth 2.1）。使用 auth 属性来提供它。

提供授权最简单的方式是通过字符串值。对于静态授权使用这种方式，比如服务范围的 API 令牌：

src/agents/project-assistant.ts
'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 '为团队管理 Linear 问题和项目。';
}

一些 MCP 服务器期望动态的每用户或每会话授权令牌。当你需要动态授权时，可以向 auth 传递一个函数而非字符串。该函数在每次请求时解析，因此令牌可以轮换和撤销，让你拥有完全控制：

export function Assistant() {
  const { userId } = useInitialData<{ userId: string }>();

  useMcpConnection({
    name: 'linear',
    url: 'https://mcp.linear.app/mcp',
    auth: () => tokenStore.get(userId, 'linear'),
  });

  return '帮助此用户管理他们的 Linear 问题。';
}

Flue 永远不会存储或管理你的令牌。你有责任自行处理 OAuth 流程、令牌存储和刷新令牌逻辑。

要在用户在对话中途授权后附加服务器，请基于持久标志有条件地声明连接：

const [linearReady, setLinearReady] = usePersistentState('linear-ready', false);

if (linearReady) {
  useMcpConnection({
    name: 'linear',
    url: LINEAR_MCP_URL,
    auth: () => tokenStore.get(userId, 'linear'),
  });
}

useAgentStart(async () => {
  if (!linearReady && (await tokenStore.has(userId, 'linear'))) setLinearReady(true);
});

当你的 OAuth 流程完成并且标志翻转时，智能体从下一条消息开始拥有服务器的工具。如果多个智能体需要共享一个用户的授权，请将集成放在你的应用中：一个应用拥有的集成服务本身可以是一个 MCP 服务器，智能体连接到它。

指定工具

服务器通常暴露数十个工具，每个挂载的工具都会占用模型上下文。tools 允许列表只挂载你列出的工具：

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

如果允许列表命名了一个服务器未暴露的工具，连接会以错误失败。

复用 MCP 服务器定义

defineMcpConnection(...) 验证一个 MCP 连接对象，这样你可以定义一次然后从任何智能体中复用它：

src/connections/linear.ts
import { defineMcpConnection } from '@flue/runtime';

export const linear = defineMcpConnection({
  name: 'linear',
  url: 'https://mcp.linear.app/mcp',
  auth: process.env.LINEAR_API_KEY,
});
import { linear } from '../connections/linear.ts';
useMcpConnection(linear);
useMcpConnection({ ...linear, tools: ['search_issues'] }); // 每次挂载覆盖字段

安全性

你连接的 MCP 服务器可以影响你的智能体：它的工具描述进入提示，它的工具结果进入对话。将你不控制的服务器视为任何其他第三方依赖，并考虑使用 tools 允许列表来限制你的暴露面。

高级：直接建立 MCP 服务器连接

createMcpConnection(definition) 是 hook 底层的更低级函数。它连接、发现服务器的工具，并将它们作为 ToolDefinition 值返回，这样受信任的应用代码可以在用 useTool 挂载之前过滤或包装它们：

const linear = await createMcpConnection({ name: 'linear', url: LINEAR_MCP_URL, auth: TOKEN });

export function ProjectAssistant() {
  useModel('anthropic/claude-sonnet-4-6');
  for (const tool of linear.tools) useTool(tool);
  return '为团队管理 Linear 问题和项目。';
}

每个适配的定义保留服务器的 MCP annotations，这样受信任的应用代码可以在挂载或包装之前检查 tool.annotations?.readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint——例如，要求对破坏性调用进行人工审批（参见审批门）。这些是服务器提供的提示，而非安全边界；仅在你信任服务器时才将它们用于审批决策。

如果你曾经直接使用 Node.js JavaScript API，这在 Node.js 脚本中也会很有用——参见独立脚本。

后续步骤