Connect

Public Beta

Mastra Connect 在 beta 期间可在 Mastra platform 上免费使用。

Connect 在你的 Mastra platform项目中管理对 GitHub、Slack 和 Linear 等服务的连接。@mastra/connect 包将这些连接以 tools、channels 或凭据的形式提供给应用。

• Tools 让 agents 调用提供方的 API。Connect 提供现成的 tools，并通过平台代理发送它们的请求，由代理添加凭据并刷新 OAuth tokens。参见 Tools。
• Channels 让人们通过 Slack、Telegram、Discord 或 Microsoft Teams 与 agents 对话。Connect 为 Mastra 的 channel providers 提供凭据。参见 Channels。
• 原始凭据让你的代码在 tools 无法满足需求时直接调用提供方的 SDK。参见 credential()。

何时使用 Connect

当你想在平台上管理提供方账户，而不是在应用中存储凭据并处理 OAuth token 刷新时，请使用 Connect。你可以在不更改 agent 代码的情况下添加或替换连接。Tool resolvers 会在其缓存刷新时获取连接变更，无需重新部署。

你可以在同一应用中组合使用 Connect tools 和 channels 与你自己的自定义 tools和自管理 channels。Connect 需要一个 platform 项目，但你的应用可以在本地或自己的基础设施上运行。

连接的工作原理

Provider 定义你可以使用的服务及其能力。Connection 授权该提供方上的一个账户。连接属于你的组织，可以链接到多个项目而无需再次授权。

一个项目可以为同一提供方拥有多个连接，例如不同 Slack workspaces 中的账户。为每个连接指定不同的显示名称，以帮助 agents 选择正确的账户。

提供方并不都提供相同的能力或授权流程。有些使用 OAuth，另一些需要 API key，渠道设置可能需要在供应商控制台中创建 bot 或应用。参见 Providers为你的用例选择提供方。

开始使用

你需要一个 Mastra platform 项目和 mastra CLI，并使用 mastra auth login 登录。

安装包

npm

npm install @mastra/connect

pnpm

pnpm add @mastra/connect

Yarn

yarn add @mastra/connect

Bun

bun add @mastra/connect

配置环境

你的应用使用 access token 向平台认证。为应用创建一个：

mastra auth tokens create my-app

将其保存为 MASTRA_PLATFORM_ACCESS_TOKEN，这是 @mastra/connect 读取的名称。CLI 会建议 MASTRA_API_TOKEN，但 @mastra/connect 会忽略它。将 token 和项目 ID 添加到应用的环境中：

.env

MASTRA_PLATFORM_ACCESS_TOKEN=your-token
MASTRA_PROJECT_ID=your-project-id

关于区域和其他可选变量，参见环境变量。

连接账户

从提供方列表中选择一个提供方，并使用其 ID 运行 mastra connect add。例如，授权一个 Linear 账户：

mastra connect add linear

从包含 .env 文件的目录运行该命令。CLI 会引导你完成提供方的授权流程。关于列出、命名、移除和替换连接，参见 mastra connect CLI 参考。

使用连接

选择你的应用如何使用已连接的账户：

• 将 tools()传递给 agent 的 tools 选项，为其提供提供方 tools，同时保留你自己定义的任何 tools。
• 将 channels()返回的提供方添加到你的 Mastra 配置，然后在 Studio 中将 channel 连接到 agent。
• 使用连接 ID 调用 credential()，在你自己的代码中使用其凭据。

安全模型

对于 tool 调用，平台会在服务器上为请求添加凭据。它会记录每个代理调用，以便你审计和统计 tool 使用情况，而不会记录 tool 参数或结果。请求只能访问提供方的 API 主机，包括任何允许的按连接主机（例如 Supabase 项目 URL）。

你的代码控制 agent 获得哪些 tools 以及哪些调用需要审批。关于配置，参见 tool 过滤。

使用原始凭据

调用 credential() 会将密钥返回给你的应用。使用它发出的请求会绕过平台代理，包括其主机限制和调用记录。不要记录该凭据，也不要将其返回到 agent 输出中。凭据参考涵盖支持的类型和过期处理。