将 MCP 流与 MSAL 浏览器配合使用

模型上下文协议(MCP) 是一种开放标准,使 AI 应用程序能够安全地连接到外部工具、数据源和服务。 MSAL 浏览器通过强制所有令牌请求包含 resource 参数并按该资源缓存访问令牌来支持 MCP 流。

注释

对于使用 PublicClientApplication 的标准浏览器应用程序以及使用 createNestablePublicClientApplication嵌套应用身份验证 (NAA) 应用程序,都支持 MCP 流。

有关服务器端实现,请参阅 MSAL 节点 MCP 流。

先决条件

启用 MCP

在创建 PublicClientApplication 时,在 auth 配置中设置 isMcp: true:

const msalConfig = {
    auth: {
        clientId: "your-client-id",
        authority: "https://login.microsoftonline.com/common",
        isMcp: true,
    },
};

const pca = new msal.PublicClientApplication(msalConfig);

对于 NAA 应用,使用与 createNestablePublicClientApplication 相同的配置:

const pca = await msal.createNestablePublicClientApplication(msalConfig);

资源参数

当 isMcp 是 true时,每个令牌请求 都必须 包含一个 resource 参数。 省略它会引发错误 resource_parameter_required 。

const tokenRequest = {
    scopes: ["User.Read"],
    resource: "https://example.microsoft.com",
};

Important

resource直接在请求对象上设置参数。 不要同时通过 extraQueryParameters 或 extraParameters 传递它,也不要与 resource 属性同时传递 — 否则会引发 misplaced_resource_parameter 错误。

以下示例显示了设置 resource 参数的正确和不正确方法:

// Correct
const request = {
    scopes: ["User.Read"],
    resource: "https://example.microsoft.com",
};

// Wrong — resource in both locations
const request = {
    scopes: ["User.Read"],
    resource: "https://example.microsoft.com",
    extraQueryParameters: { resource: "https://example.microsoft.com" },
};

资源范围缓存

启用 isMcp 后,访问令牌会连同其关联的资源一起缓存。 此行为影响静默令牌获取:

  • 缓存命中:如果同一作用域和资源存在缓存的访问令牌,则从缓存返回该令牌。
  • 缓存未命中:如果请求的资源与任何缓存的令牌都不匹配,MSAL 会回退到网络以获取请求资源的新令牌。
// First request — acquires token from network
const token1 = await pca.acquireTokenSilent({
    scopes: ["User.Read"],
    resource: "https://resource-a.microsoft.com",
    account: account,
});

// Same resource — returns cached token
const token2 = await pca.acquireTokenSilent({
    scopes: ["User.Read"],
    resource: "https://resource-a.microsoft.com",
    account: account,
});

// Different resource — falls back to network
const token3 = await pca.acquireTokenSilent({
    scopes: ["User.Read"],
    resource: "https://resource-b.microsoft.com",
    account: account,
});

错误处理

两个错误是 MCP 流程特有的:

错误代码 Description
resource_parameter_required isMcp 是 true ,但请求不包含参数 resource 。
misplaced_resource_parameter 在 resource 属性和 extraQueryParameters 或 extraParameters 中都找到了 resource。 只使用一个。

这两个错误都会作为 ClientAuthError 被抛出。 有关详细信息,请参阅 错误文档。

后续步骤