Gunakan alur MCP dengan MSAL Node

Saat membangun aplikasi Model Context Protocol (MCP), Anda dapat mengonfigurasi MSAL Node untuk menerapkan perolehan dan penyimpanan token dalam cache berdasarkan cakupan sumber daya. Ketika mode MCP diaktifkan, MSAL mengharuskan setiap permintaan token untuk menyertakan resource parameter dan cache token akses yang dikunci oleh sumber daya tersebut.

Note

Alur MCP hanya tersedia untuk aplikasi klien publik.

Prasyarat

Aktifkan mode MCP

Tetapkan isMcp: true dalam konfigurasi auth saat membuat PublicClientApplication:

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

const pca = new msal.PublicClientApplication(config);

Sertakan parameter sumber daya

Ketika isMcp adalah true, setiap permintaan token harus menyertakan resource parameter. Menghilangkannya akan menimbulkan resource_parameter_required kesalahan.

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

const response = await pca.acquireTokenByCode(tokenRequest);

Important

Atur resource parameter langsung pada objek permintaan. Jangan meneruskannya melalui extraQueryParameters bersamaan dengan properti resource — hal tersebut akan menimbulkan error misplaced_resource_parameter.

Contoh berikut menunjukkan cara yang benar dan salah untuk mengatur resource parameter:

// 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 dalam lingkup sumber daya

Saat isMcp diaktifkan, token akses di-cache dengan sumber daya terkait. Ini berdampak pada perolehan token secara senyap:

  • Hit cache: Jika ada token akses cache untuk cakupan dan sumber daya yang sama, token tersebut dikembalikan dari cache.
  • Cache miss: Jika sumber daya yang diminta tidak cocok dengan token apa pun yang tersimpan dalam cache, MSAL menggunakan jaringan untuk memperoleh token baru bagi sumber daya yang diminta.
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],
});

Penanganan kesalahan

Dua kesalahan khusus untuk alur MCP:

Kode kesalahan Deskripsi
resource_parameter_required isMcp adalah true tetapi permintaan tidak menyertakan resource parameter.
misplaced_resource_parameter Sebuah resource ditemukan baik dalam properti resource maupun di extraQueryParameters. Gunakan hanya satu.

Kedua kesalahan dilemparkan sebagai ClientAuthError. Untuk informasi selengkapnya, lihat FAQ MSAL Node.

Sampel

  • Sampel Alur MCP — Aplikasi ekspres yang menunjukkan MCP dengan kode otorisasi dan alur senyap.

Langkah berikutnya

Menginisialisasi aplikasi klien publik

  • Last updated on