Menggunakan alur MCP dengan Browser MSAL

Model Context Protocol (MCP) adalah standar terbuka yang memungkinkan aplikasi AI terhubung dengan aman dengan alat eksternal, sumber data, dan layanan. MSAL Browser mendukung alur MCP dengan memastikan bahwa semua permintaan token menyertakan parameter resource dan menyimpan token akses dalam cache yang diindekskan berdasarkan sumber daya tersebut.

Note

Alur MCP didukung untuk aplikasi browser standar menggunakan PublicClientApplication dan aplikasi Autentikasi Aplikasi Berlapis (NAA) menggunakan createNestablePublicClientApplication.

Untuk implementasi sisi server, lihat Alur MSAL Node MCP.

Prasyarat

Mengaktifkan MCP

Tetapkan isMcp: true dalam konfigurasi auth saat membuat PublicClientApplication:

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

const pca = new msal.PublicClientApplication(msalConfig);

Untuk aplikasi NAA, gunakan konfigurasi yang sama dengan createNestablePublicClientApplication:

const pca = await msal.createNestablePublicClientApplication(msalConfig);

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"],
    resource: "https://example.microsoft.com",
};

Important

Atur resource parameter langsung pada objek permintaan. Jangan meneruskannya melalui extraQueryParameters atau extraParameters bersamaan dengan properti resource—hal itu akan memunculkan kesalahan misplaced_resource_parameter.

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

// 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" },
};

Cache dalam lingkup sumber daya

Saat isMcp diaktifkan, token akses di-cache dengan sumber daya terkait. Perilaku ini memengaruhi 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.
// 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,
});

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 resource ditemukan baik di properti resource maupun di extraQueryParameters atau extraParameters. Gunakan hanya satu.

Kedua kesalahan dilemparkan sebagai ClientAuthError. Untuk informasi selengkapnya, lihat dokumentasi kesalahan.

Langkah berikutnya

Menginisialisasi aplikasi

  • Last updated on