Używanie przepływów MCP z przeglądarką MSAL

Model Context Protocol (MCP) to otwarty standard, który umożliwia aplikacjom sztucznej inteligencji bezpieczne łączenie się z zewnętrznymi narzędziami, źródłami danych i usługami. MSAL Browser obsługuje przepływy MCP, wymuszając dołączanie parametru resource do wszystkich żądań tokenów oraz buforując tokeny dostępu według tego zasobu.

Note

Przepływy MCP są obsługiwane zarówno w przypadku standardowych aplikacji przeglądarkowych korzystających z PublicClientApplication, jak i aplikacji z uwierzytelnianiem aplikacji zagnieżdżonych (NAA, Nested App Authentication) korzystających z createNestablePublicClientApplication.

Aby zapoznać się z implementacjami po stronie serwera, zobacz Przepływy MCP węzła MSAL.

Wymagania wstępne

Włączanie MCP

Ustaw isMcp: true w konfiguracji auth podczas tworzenia swojego PublicClientApplication:

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

const pca = new msal.PublicClientApplication(msalConfig);

W przypadku aplikacji NAA użyj tej samej konfiguracji z createNestablePublicClientApplication:

const pca = await msal.createNestablePublicClientApplication(msalConfig);

Parametr zasobu

Gdy isMcp ma wartość true, każde żądanie uzyskania tokenu musi zawierać parametr resource. Pominięcie tego powoduje błąd resource_parameter_required.

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

Ważna

resource Ustaw parametr bezpośrednio na obiekcie żądania. Nie przekazuj go za pośrednictwem extraQueryParameters ani extraParameters jednocześnie z właściwością resource — spowoduje to wystąpienie błędu misplaced_resource_parameter.

W poniższym przykładzie przedstawiono poprawne i nieprawidłowe sposoby ustawiania parametru 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" },
};

Buforowanie w zakresie zasobów

Po isMcp włączeniu tokeny dostępu są buforowane z skojarzonym zasobem. To zachowanie ma wpływ na pozyskiwanie tokenów dyskretnych:

  • Trafienie w pamięci podręcznej: jeśli w pamięci podręcznej istnieje token dostępu dla tych samych zakresów i zasobu, jest on z niej zwracany.
  • Brak pamięci podręcznej: jeśli żądany zasób nie jest zgodny z żadnym tokenem buforowanym, biblioteka MSAL wraca do sieci, aby uzyskać nowy token dla żądanego zasobu.
// 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,
});

Obsługa błędów

Dwa błędy są specyficzne dla przepływów MCP:

Kod błędu Description
resource_parameter_required isMcp ma wartość true, ale żądanie nie zawiera parametru resource.
misplaced_resource_parameter Znaleziono element resource zarówno we właściwości resource, jak i w extraQueryParameters lub extraParameters. Użyj tylko jednego.

Oba błędy są zgłaszane jako ClientAuthError. Aby uzyskać więcej informacji, zobacz dokumentację błędów.

Następne kroki

Inicjowanie aplikacji

  • Last updated on