MCP 认证
你要么将 Mastra 应用连接到他人受保护的 MCP 服务器，要么将自己的工具和数据暴露给第三方客户端。两个方向需要不同的凭据和不同的检查。
无论哪个方向，MCP 连接都会跨越多个安全边界：对调用方进行认证，并不决定其可以读取哪些客户记录；拥有连接权限，也不代表可以执行每一项工具操作。请将凭据、委托访问和应用权限视为彼此独立的决策。
本指南从 Mastra 作为 MCP 客户端和服务器的角度解释这些决策。协议要求引用 2026 年 7 月 28 日的 MCP 授权规范。
理解边界理解边界的直接链接
以下三个决策回答不同的问题：
- 认证（Authentication） 验证调用方的身份，例如某个用户或服务账号。
- 委托访问（Delegated access） 允许客户端以授权服务器授予的访问权限行事。OAuth 访问令牌授予对其预期资源的访问，并不是通用的身份凭据。
- 应用授权（Application authorization） 决定调用方是否可以对其组织中的某张发票执行更新等数据操作。
在 HTTP OAuth 流程中，这些是彼此独立的角色，而不是同一个服务：
MCP 服务器是受保护的资源，未必是负责让用户登录的服务。授权服务器负责签发令牌，可以与 MCP 服务器分离。客户端负责获取并出示令牌。在用户委托流程中，授权服务器会按需与用户交互，完成认证和同意。并非每个流程都需要用户交互。
你的应用处于这幅图中的哪个位置，决定了它管理哪些凭据。使用 MCPClient 时，你的 Mastra 应用连接到另一个 MCP 服务器。使用 MCPServer 时，你的应用向其他客户端暴露能力。同一个应用可以两者兼做，但它的入站凭据与出站凭据服务于不同的边界。
MCP 授权是可选的。对于 HTTP 传输，支持授权的实现应遵循该规范。使用 stdio 的实现应改为从环境中获取凭据，而不应使用这套 HTTP 授权流程。请先选择传输方式，再选择凭据机制。
连接到受保护的 MCP 服务器连接到受保护的 MCP 服务器的直接链接
根据远程服务器应强制执行谁的访问权限来选择凭据：
| 访问模型 | Mastra 集成方式 | 应用职责 |
|---|---|---|
| 共享服务访问 | 通过 MCPClient 请求头或自定义 fetch 配置特定服务器的凭据。 | 限制该服务账号的访问范围。不要把共享凭据当作最终用户权限的证明。 |
| 由每个用户委托的访问 | 通过 authProvider 为每个服务器配置单独的 MCPOAuthClientProvider。 | 隔离每个用户的 provider、连接、令牌和已存储的注册状态。 |
关于静态工具和运行时工具，请参阅 MCP 连接配置；关于 provider 配置和存储，请参阅 OAuth 客户端参考。
为每个 MCP 服务器使用单独的 provider 只能做一件事，而不能做另一件事：
- 它可以防止该 provider 的授权会话状态在多个服务器之间共享。
- 它不能隔离用户或授权服务器签发者（issuer）。Mastra 默认的 OAuth 存储位于内存中。自定义
OAuthStorage控制持久化，因此请将该存储的作用域限定到用户和连接。 - 它无法替你绑定凭据与签发者。规范要求注册凭据绑定到签发者，并为不同授权服务器保留独立的注册状态和令牌状态，因此签发者变更时不要复用这些凭据。
注册与浏览器回调注册与浏览器回调的直接链接
规范建议支持 Client ID Metadata Documents（CIMD），它通过 HTTPS 元数据 URL 标识客户端。规范还定义了预注册（pre-registration）。支持所有注册选项的客户端应优先使用现有的预注册信息。旧版动态客户端注册（DCR）仍为兼容性保留且是可选的，但对于新实现已弃用。参见带版本的客户端注册规则。
Mastra 的 provider 接受预注册的客户端信息，并支持基于 DCR 的流程。不要因为存在 OAuth 支持就推断其支持 CIMD。在选择部署方式前，请确认你的客户端集成和授权服务器所支持的注册机制。
Mastra 的交互式 authenticate() 流程使用本地回环回调服务器。它不是托管式的多用户登录端点。托管应用必须拥有自己的回调端点，并将每次授权尝试与正确的用户和 provider 关联。参见交互式浏览器认证。
授权响应职责授权响应职责的直接链接
对于你选择的客户端集成，请区分以下协议职责：
- 客户端必须实现 Proof Key for Code Exchange（PKCE），验证授权服务器声明支持 PKCE，并在技术上可行时使用
S256。 - 重定向 URI 必须使用 HTTPS 或 localhost。授权服务器必须精确匹配已注册的重定向 URI。客户端应使用并验证 OAuth
state。
客户端还必须拒绝任何授权响应，只要其 iss 值与从经验证的授权服务器元数据中记录的签发者不完全一致。客户端应做什么取决于响应内容以及服务器是否声明 authorization_response_iss_parameter_supported：
授权响应中的 iss | 服务器声明支持 iss | 客户端操作 |
|---|---|---|
| 存在且与记录的签发者完全一致 | 任意值 | 继续 |
| 存在但不一致 | 任意值 | 在交换 code 之前拒绝 |
| 缺失 | true | 在交换 code 之前拒绝 |
| 缺失 | false 或未声明 | 允许 |
参见授权响应验证规则。验证 state 并不是签发者验证。
在依赖所选集成的 authProvider 配置之前，请确认这些职责。 安全注意事项定义了完整规则。
保护 Mastra MCP 服务器保护 Mastra MCP 服务器的直接链接
请先区分两个问题：客户端如何发现从哪里获取令牌，以及你的服务器如何验证该令牌？
如果你的服务器使用授权，协议流程如下：
- 客户端发现 MCP 服务器的受保护资源元数据（Protected Resource Metadata），其中标识了其授权服务器。
- 客户端发现所选授权服务器的元数据，并为该 MCP 服务器获取令牌。
- MCP 服务器验证令牌，然后由应用对请求的操作进行授权。
规范要求提供受保护资源元数据和授权服务器发现。声明签发者或支持的 scopes 并不能验证令牌或强制执行权限。参见授权服务器发现。
关于令牌使用，客户端必须在授权请求和令牌请求中将 MCP 服务器的规范 URI 作为 resource 包含在内，然后通过 Authorization 请求头发送访问令牌，绝不能放在查询字符串中。服务器必须验证令牌有效且面向自己（包括其受众 audience），并对无效或过期令牌返回 HTTP 401。
Mastra 的 createOAuthMiddleware 可以在没有 bearer token 的情况下提供受保护资源元数据并发起质询（challenge）请求。它会调用已配置的令牌验证器，并拒绝标记为无效的结果。
如果没有验证器，中间件会接受未经验证的令牌。该行为仅用于开发和测试，不提供生产级别的保护。
请根据你的签发者配置相应的验证，包括受众和过期检查。验证结果还需要与你工具所信任的身份关联起来。该中间件不会替你完成身份映射。
使用 server.auth 保护 Mastra 路由与提供可互操作的 OAuth 发现是两项不同的任务。不要以为配置了其中一个就自动具备另一个。
Mastra 为 MCP 服务器注册的路由Mastra 为 MCP 服务器注册的路由的直接链接
除 MCP 传输之外，Mastra 还注册了 Studio 用来列出服务器、检查工具、执行工具和读取资源的 REST 路由。完整列表请参阅 MCP 路由参考。这些路径使用默认的 /api 前缀。
POST /api/mcp/:serverId/tools/:toolId/execute 路由会直接调用 executeTool()，不经过协议客户端。配置 Mastra FGA provider 后，MCPServer.executeTool() 会使用 requestContext 中的用户强制执行工具执行权限。REST 工具列表也会通过 FGA 过滤工具。这些权限检查不能替代路由认证。
这些路由的内置认证取决于 server.auth。如果没有它，requiresAuth: true 不会强制认证。仅检查 /mcp 或 /sse 传输路径的自定义中间件会让 REST 路由保持开放。如果你使用自定义中间件而不是 server.auth，请对 /api/mcp/* 默认拒绝，并仅在认证后允许访问。
将已验证身份传给工具将已验证身份传给工具的直接链接
当 Mastra 服务器处理 MCP 请求时，其认证桥接会保留已有的 req.auth。否则，它会在已配置时使用 server.mcpOptions.setRequestAuth，或从请求上下文构建 authInfo。使用默认桥接时，已认证用户可在 authInfo.extra.user 中获取。
请用可信的认证结果填充该身份，因为字段映射本身并不验证凭据。关于桥接机制，请参阅将身份转发给 MCP 工具；关于映射参考，请参阅 authInfo 的来源。
授权工具与数据授权工具与数据的直接链接
OAuth scopes 描述已授予的访问权限，但不能取代应用的权限和所有权检查。规范建议请求最小权限的 scope，并描述了当操作需要更多访问权限时的升级授权（step-up authorization）。不要以为 Mastra 会自动组合 scopes，或针对你的应用策略发出 scope 不足的质询。
配置 Mastra FGA provider 后，MCPServer 会过滤 tools/list，并在 tools/call 上强制执行工具执行授权。mapAuthInfoToUser 会将可信的 MCP 认证信息映射为这些检查所消费的用户。关于策略设置，请参阅细粒度授权；关于 MCP 特定的映射，请参阅 MCPServer 配置。
仅仅隐藏工具并不够：调用方可以不先列出工具就直接尝试调用。应将授权保留在调用时，并检查所请求的每条记录都属于调用方有权访问的组织或用户。请从可信的服务器上下文解析调用方和租户，而不是从模型提供的工具参数中解析。人工审批可以确认预期操作，但不能取代这些检查。
MCP 工具 FGA 集成不会自动授权资源、提示词或订阅，其映射也不适用于内部 agent 或 workflow 的工具执行。如果你暴露了这些面，请在应用代码中进行授权。
不要以为工具权限能保护你通过资源、提示词或订阅暴露的调用方敏感数据。
安全访问上游服务安全访问上游服务的直接链接
MCP 访问令牌是给 MCP 服务器用的。规范禁止将该令牌透传给上游 API。当工具调用另一个服务时，请使用专用于该服务的独立凭据，并由可信的应用代码为已授权用户或租户选择。
请将访问令牌、刷新令牌和服务凭据置于模型可见的指令、工具参数和工具结果之外。只返回任务所需的数据。认证与身份指南解释了这一模型边界。
生产前验证生产前验证的直接链接
- 验证令牌： 为签发者配置验证，包括受众和过期检查，并确认未经验证的令牌会被拒绝。
- 对缺失令牌发起质询： 确认每个受保护的服务器路径在没有 bearer token 时返回
401。 - 保护 MCP REST 路由： 如果你不使用
server.auth，请确认/api/mcp/:serverId/tools*、/api/mcp/:serverId/resources*和/api/mcp/v0/servers*在没有认证时不可访问。如果你配置的 API 前缀不是/api，请相应调整。 - 隔离用户： 确认一个用户的 provider、连接和已存储凭据不会被另一个用户复用。
- 将凭据绑定到签发者： 确认授权服务器变更时，注册信息和令牌不会被复用。
- 拒绝未授权操作： 确认无权限的调用方在
tools/call和POST /api/mcp/:serverId/tools/:toolId/execute上均被拒绝，包括其从未列出过的工具。 - 将记录限定到调用方： 确认记录查询从可信的服务器上下文而不是工具参数解析租户。
- 让令牌留在其受众范围内： 确认上游调用使用独立凭据，绝不转发 MCP 令牌。
- 将密钥排除在模型数据之外： 确认令牌和凭据不会出现在指令、工具参数和工具结果中。
后续步骤后续步骤的直接链接
- 使用 MCP 连接配置和
MCPClient参考连接到受保护的服务器。 - 在
MCPServer参考中暴露你自己的工具，并查看传输和上下文选项。 - 使用细粒度授权添加权限检查。
- 通过认证与身份指南追踪来自入站请求的身份。