Utilizar os fluxos MCP com o MSAL Node

Ao desenvolver aplicações Model Context Protocol (MCP), pode configurar o MSAL Node para impor a aquisição e a colocação em cache de tokens delimitadas por recurso. Quando o modo MCP está ativado, o MSAL exige que cada pedido de token inclua um resource parâmetro e armazena em cache tokens de acesso selecionados por esse recurso.

Pré-requisitos

• Registar uma aplicação na plataforma de identidade da Microsoft
• Uma aplicação configurada como cliente público (por exemplo, uma aplicação de ambiente de trabalho ou CLI)
• @azure/msal-node versão 5 ou superior instalada no seu projeto

Ativar o modo MCP

Defina isMcp: true na configuração auth ao criar o seu PublicClientApplication:

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

const pca = new msal.PublicClientApplication(config);

Incluir o parâmetro de recurso

Quando isMcp é true, cada pedido de token deve incluir um resource parâmetro. Omitir isso gera um resource_parameter_required erro.

const tokenRequest = {
    scopes: ["User.Read"],
    redirectUri: "http://localhost:3000/redirect",
    resource: "https://example.microsoft.com",
    code: authorizationCode,
};

const response = await pca.acquireTokenByCode(tokenRequest);

O exemplo seguinte mostra as formas corretas e incorretas de definir o resource parâmetro:

// Correct — resource on the request object
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" },
};

Cache com escopo de recursos

Quando isMcp está ativado, os tokens de acesso são armazenados em cache com o seu recurso associado. Isto afeta a aquisição silenciosa de tokens:

• Impacto na cache: Se existir um token de acesso em cache para os mesmos escopos e recurso, ele é devolvido da cache.
• Cache miss: Se o recurso solicitado não corresponder a nenhum token em cache, o MSAL recorre à rede para adquirir um novo token para o recurso solicitado.

const msalTokenCache = pca.getTokenCache();
const accounts = await msalTokenCache.getAllAccounts();

// First request — acquires token from network
const token1 = await pca.acquireTokenSilent({
    scopes: ["User.Read"],
    resource: "https://resource-a.microsoft.com",
    account: accounts[0],
});

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

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

Tratamento de erros

Dois erros são específicos dos fluxos MCP:

Ambos os erros são apresentados como ClientAuthError. Para mais informações, consulte as Perguntas Frequentes sobre MSAL Node.

Samples

• MCP Flows Sample — Aplicação Express que demonstra o MCP com código de autorização e fluxos silenciosos.

Passos seguintes

• Concessões de código de autorização suportadas
• Armazenamento em cache de tokens no MSAL Node
• Perguntas Frequentes sobre o MSAL Node