Przewodnik wdrożenia autoryzacji serwera MCP: korzystanie z najnowszej specyfikacji

Kilka dni temu (18 czerwca 2025 r.) zespół MCP (Model Context Protocol) opublikował najnowszą wersję specyfikacji MCP (2025-06-18). Ta aktualizacja obejmuje kluczową zmianę w specyfikacji autoryzacji. Serwery MCP nie będą już wydawały tokenów dostępu jako Serwer autoryzacyjny. Zamiast tego, będą konsumować tokeny dostępu i udostępniać zasoby jako Serwer zasobów.

Jako jeden z maintainerów MCP Auth (biblioteka plug-and-play do autoryzacji serwera MCP), zaimplementowałem wsparcie dla najnowszej specyfikacji MCP auth w tym projekcie. Na podstawie mojego doświadczenia praktycznego pokażę, jak wdrożyć funkcje uwierzytelniania dla twojego serwera MCP zgodnie z najnowszą specyfikacją.

Ten artykuł pomoże ci:

• Zrozumieć, jak działa uwierzytelnianie MCP zgodnie z nową specyfikacją MCP auth
• Wyjaśnić, co serwery MCP muszą wdrożyć jako serwery zasobów zgodnie z wymaganiami specyfikacji MCP auth
• Dostarczyć wskazówek dotyczących wdrażania wsparcia uwierzytelniania spełniającego wymagania najnowszej specyfikacji MCP auth dla twojego serwera MCP
• Zidentyfikować pomijane punkty i problemy bezpieczeństwa podczas wdrażania specyfikacji MCP auth

Prosimy pamiętać, że ten artykuł:

• Zakłada, że czytelnicy mają podstawową wiedzę o JWT (JSON Web Token). Artykuł nie omawia szczegółowo struktury JWT, weryfikacji podpisu i innych podstawowych koncepcji. Po więcej informacji zobacz Auth Wiki - JWT
• Nie wprowadza szczegółowo różnych RFC, od których zależy specyfikacja MCP auth. Przedstawia tylko wdrożenia zgodne z wymaganiami tych RFC
• Nie omawia implementacji klientów MCP oraz implementacji i szczegółów interakcji związanych z autoryzacją. Zwykle realizują je klienci LLM i dostawcy serwerów autoryzacyjnych wspierających MCP zgodnie ze specyfikacjami MCP. Programiści serwerów MCP nie muszą oraz nie mogą ingerować w te implementacje. Po więcej informacji zobacz OAuth Client i Authorization Server
• Wszystkie tokeny dostępu wspomniane w artykule są traktowane jako JWT, bo to najczęściej używany format na rynku. Inne rodzaje tokenów należy wykorzystywać zgodnie z dokumentacją odpowiedniego dostawcy serwera autoryzacyjnego.

Jak działa uwierzytelnianie MCP?#

Zgodnie z najnowszą specyfikacją MCP auth, przebieg uwierzytelniania MCP pokazany jest na poniższym diagramie:

1. Klient MCP żąda zasobów od serwera MCP pod adresem https://github-tools.com. Ponieważ użytkownik nie jest jeszcze zalogowany, nagłówek autoryzacji HTTP tego żądania nie zawiera tokenu dostępu reprezentującego użytkownika.

2. Serwer MCP nie może pobrać tokenu dostępu z nagłówka autoryzacji żądania klienta MCP. Wysyła klientowi MCP błąd HTTP 401. Ta odpowiedź błędu zawiera nagłówek WWW-Authenticate, który zawiera adres URL metadanych zasobów serwera MCP (wartość pola resource_metadata).

3. Klient MCP wyodrębnia wartość resource_metadata ze zwróconego nagłówka WWW-Authenticate (na przykład: https://github-tools.com/.well-known/oauth-protected-resource). Następnie klient MCP żąda metadanych zasobów udostępnionych przez serwer MCP jako Serwer Zasobów pod tym adresem. Te metadane zawierają takie informacje, jak authorization_servers i scopes_supported, pomagając klientowi MCP zrozumieć, jak uzyskać token dostępu potrzebny do dostępu do serwera MCP, na przykład z którego serwera autoryzacji pobrać token z odpowiednimi uprawnieniami.

4-8. Klient MCP żąda informacji o metadanych serwera autoryzacji na podstawie adresu URL metadanych serwera autoryzacji uzyskanego z metadanych zasobów. Następnie klient MCP przeprowadza proces autoryzacji OAuth 2.1 z serwerem autoryzacyjnym i po zakończeniu autoryzacji uzyskuje token dostępu.

9. Klient MCP zabiera otrzymany z serwera autoryzacji token dostępu i ponownie żąda zasobu od serwera MCP.

10. Serwer MCP zwraca żądany zasób po zweryfikowaniu poprawności tokenu. Następnie komunikacja pomiędzy klientem MCP a serwerem MCP odbywa się z ważnym tokenem.

W kolejnych sekcjach przedstawimy, jak krok po kroku wdrożyć mechanizm uwierzytelniania serwera MCP w oparciu o przebieg MCP auth.

Obsłuż żądania nieautoryzowane: zwracaj błąd 401 i nagłówek WWW-Authenticate#

Jak pokazano powyżej, gdy klient MCP przesyła żądanie do serwera MCP bez tokenu dostępu, serwer MCP powinien zwrócić błąd HTTP 401 Unauthorized z nagłówkiem WWW-Authenticate zawierającym adres URL do pobrania metadanych zasobów serwera MCP.

Zgodnie z wymaganiami dotyczącymi obsługi błędów specyfikacji MCP auth, oprócz sytuacji, gdy klient MCP nie przesyła tokenu dostępu, także jeśli serwer MCP otrzyma nieprawidłowy token dostępu, powinien również zwrócić błąd 401 z nagłówkiem WWW-Authenticate.

Skoro już wiemy, kiedy należy zwracać błąd 401, jak zbudować zwracany nagłówek WWW-Authenticate?

Według RFC9728 Sekcja 5.1, nagłówek WWW-Authenticate musi zawierać parametr resource_metadata wskazujący adres URL chronionych metadanych zasobu.

Podstawowy format wygląda tak:

Tutaj Bearer to schemat autoryzacji oznaczający, że dostęp do zasobów chronionych OAuth 2.0 wymaga tokenu nośnika (patrz: dokumentacja MDN). Wartość parametru resource_metadata to pełny adres URL endpointa metadanych zasobu udostępnianego przez twój serwer MCP.

Przykładowa implementacja kodu wygląda tak:

Gdy klient MCP otrzyma taki błąd 401, uzyska dostęp do metadanych zasobów serwera MCP za pośrednictwem wartości resource_metadata z nagłówka WWW-Authenticate. Następnie, w oparciu o informacje z metadanych zasobów, zainicjuje żądanie autoryzacyjne do wskazanego serwera autoryzacyjnego, by uzyskać token dostępu, który pozwoli mu korzystać z serwera MCP.

Znamy już warunki zwracania błędu 401 i obowiązek zwracania adresu URL resource_metadata. Jednak wciąż nie wiemy jak zbudować ten adres i co te metadane zawierają. To opiszemy w kolejnych sekcjach.

Wdróż mechanizm odkrywania metadanych zasobu#

Według przebiegu uwierzytelniania MCP, po otrzymaniu błędu 401 klient MCP natychmiast żąda metadanych zasobu od serwera MCP. Zatem serwer MCP jako Serwer Zasobów powinien wdrożyć mechanizm odkrywania metadanych zasobu.

Określ ścieżkę URL endpointa metadanych#

W systemie OAuth używamy adresów URL do identyfikowania lokalizacji zasobów. Ten adres nazywa się "wskaźnikiem zasobu" (resource indicator). Zgodnie z RFC9728, metadane zasobu powinny być hostowane pod określoną ścieżką /.well-known.

Jeśli twój serwer MCP (np. https://github-tools.com) udostępnia tylko jedną usługę, endpoint metadanych powinien być ustawiony na:

Jeśli na jednym hoście oferujesz wiele różnych usług MCP, każda z nich powinna mieć własny endpoint metadanych. Przykładowo, platforma https://api.acme-corp.com udostępnia takie usługi:

• https://api.acme-corp.com/github - integracja z GitHub
• https://api.acme-corp.com/slack - integracja ze Slack
• https://api.acme-corp.com/database - usługa zapytań do bazy danych

Odpowiadające im endpointy metadanych powinny wyglądać tak:

• https://api.acme-corp.com/.well-known/oauth-protected-resource/github
• https://api.acme-corp.com/.well-known/oauth-protected-resource/slack
• https://api.acme-corp.com/.well-known/oauth-protected-resource/database

Zaletą tego rozwiązania jest możliwość przypisania do każdej usługi innych zakresów uprawnień i konfiguracji serwerów autoryzacyjnych, np.:

• GitHub korzysta z serwera OAuth GitHub, wymaga uprawnień github:read, github:write
• Slack korzysta z serwera OAuth Slack, wymaga uprawnień slack:channels:read, slack:messages:write
• Baza danych korzysta z wewnętrznego serwera autoryzacyjnego firmy, wymaga uprawnienia db:query

Na tej podstawie możemy podsumować, że adresy endpointów metadanych mają następujący wzór:

Możemy uzyskać adres endpointa metadanych na podstawie wskaźnika zasobów w ten sposób:

Zbuduj odpowiedź z metadanymi zasobu#

Po ustaleniu ścieżki endpointa URL, musimy sprawić, by ten endpoint zwracał metadane w formacie JSON zgodnie z wymogami RFC9728.

W praktyce skupiamy się na czterech kluczowych polach.

Pierwsze to pole resource, czyli wskaźnik zasobu — powinien być zgodny z adresem zasobu, do którego chce uzyskać dostęp klient MCP.

Kolejne to pole authorization_servers, będące tablicą określającą, z których serwerów autoryzacyjnych klient MCP powinien uzyskać token dostępu. Zgodnie z OAuth 2.0 Protected Resource Metadata (RFC 9728), pole to jest opcjonalne. Jednak specyfikacja MCP auth wymaga tego pola, ponieważ klient MCP musi jednoznacznie wiedzieć, do którego serwera autoryzacyjnego wysłać żądanie autoryzacji. Bez tych informacji nie jest możliwe dokończenie procesu OAuth.

Następne jest pole scopes_supported, które zawiera listę wszystkich zakresów uprawnień obsługiwanych przez ten serwer zasobów.

Ostatnie to pole bearer_methods_supported, które informuje klienta MCP o obsługiwanych przez ten serwer metodach przekazywania tokenów dostępu. Najczęściej ustawiamy ["header"], co oznacza, że po uzyskaniu tokenu dostępu od serwera autoryzacyjnego klient MCP powinien przesyłać token do serwera MCP przez nagłówek HTTP Authorization.

Spójrzmy na konkretny przykład. Chcemy skonfigurować metadane zasobu dla serwera MCP pod adresem https://github-tools.com:

Ta konfiguracja przekazuje klientowi MCP kilka istotnych informacji: chce uzyskać dostęp do zasobu https://github-tools.com, musi pobrać token dostępu z serwera autoryzacyjnego https://auth.github-tools.com, może starać się o uprawnienia takie jak github:read, github:write, repo:admin i powinien przekazywać uzyskany token za pomocą nagłówka HTTP Authorization.

W większości przypadków konfiguracja tych czterech podstawowych pól wystarcza, by klient MCP poprawnie działał. Przy bardziej złożonych przypadkach konfiguracji, sprawdź pełną listę pól w RFC9728, by poznać wszystkie dostępne opcje.

Walidacja tokenów dostępu#

Po uzyskaniu tokenu dostępu z serwera autoryzacyjnego klient MCP przekazuje ten token i próbuje uzyskać dostęp do serwera MCP.

W praktyce podczas walidowania tokenów serwer MCP powinien zwrócić uwagę na:

1. Przy podstawowej walidacji tokenów, polegać na konfiguracji serwera MCP, a nie na informacjach z tokenu (np. serwer autoryzacyjny odczytany z „issuer” w tokenie).
2. Zawsze sprawdzać, czy odbiorcą tokenu (audience) jest sam serwer MCP, aby upewnić się, że token wystawiono do zasobów tego serwera.
3. Poprawnie obsłużyć walidację zakresów uprawnień (scope).

Użyj konfiguracji serwera MCP do walidowania tokenów dostępu#

Po otrzymaniu tokenu dostępu serwer MCP, widząc że token zawiera informację o serwerze autoryzacyjnym (issuer), może chcieć pobrać konfigurację walidacji z tego issuer. Jest to zwłaszcza kuszące, gdy metadane zasobu MCP zawierają wiele serwerów autoryzacyjnych, np.:

W takiej sytuacji programiści często wyodrębniają issuer z niezweryfikowanego tokenu, by dopasować go do danych odpowiedniego serwera autoryzacyjnego i użyć do walidacji. Atakujący mogą jednak stworzyć złośliwy serwer autoryzacyjny i wystawić sfałszowany token dostępu dla serwera MCP. Jeśli backend kieruje się informacją o issuer z takiego tokenu (i ufa temu serwerowi) — walidacja przejdzie prawidłowo, mimo że token jest nielegalny.

Prawidłowa metoda weryfikacji powinna być taka:

• Gdy skonfigurowano tylko jeden serwer autoryzacyjny: waliduj token zgodnie z ustaloną konfiguracją backendu
• Gdy skonfigurowano wiele serwerów autoryzacyjnych: najpierw wyodrębnij issuer z niezweryfikowanego tokenu i znajdź go w konfiguracji serwera MCP. Jeśli taki serwer nie istnieje — odrzuć token

Oczywiście podczas walidowania tokenu należy bezwzględnie zweryfikować jego issuer.

Na przykładzie biblioteki jose JWT:

Waliduj odbiorcę tokenu (audience)#

Sekcja Token Audience Binding and Validation w specyfikacji MCP auth wskazuje, że klient żądając tokenu dostępu od serwera autoryzacji musi podać, do jakiego zasobu zostanie on użyty. Serwer MCP też musi sprawdzić, czy odbiorcą (audience) jest on sam.

To opiera się na standardzie Resource Indicators for OAuth 2.0 (RFC 8707). Mówiąc prosto:

1. Faza żądania przez klienta: Klient MCP żądając tokenu od serwera autoryzacji, przekazuje parametr resource, informujący, na jakim serwerze zasobów token będzie użyty (np. https://github-tools.com)

2. Faza wydania tokenu: Serwer autoryzacyjny wiąże ten adres zasobu i wpisuje go do tokenu jako pole audience (aud) w JWT

3. Faza walidacji tokenu: Serwer MCP musi sprawdzić, czy pole audience w tokenie JWT dokładnie odpowiada jego własnemu wskaźnikowi zasobu

Przykład dla naszego serwera MCP https://github-tools.com:

Ta weryfikacja audience to kluczowy mechanizm bezpieczeństwa zapobiegający nadużyciom tokenów. Bez tego atakujący mogą próbować użyć tokenów wystawionych dla innych usług, by uzyskać dostęp do twojego serwera MCP. Jeśli nie walidujesz audience, możesz omyłkowo zaakceptować tokeny, których akceptować nie powinieneś.

Walidacja uprawnień (scope)#

Niektóre serwery MCP zarządzają dostępem do wewnętrznych zasobów i różni użytkownicy mogą mieć różne zakresy uprawnień.

Po poprawnym zwalidowaniu tokenu dostępu trzeba sprawdzić, czy ten token zawiera wszystkie wymagane uprawnienia — wystarczy sprawdzić, czy pole scope w tokenie zawiera uprawnienie potrzebne do zasobu:

Zwróć uwagę, że zgodnie z specyfikacją MCP auth, gdy token nie ma wymaganego scope do danego zasobu, należy zwrócić błąd 403 Forbidden.

Podsumowanie#

Po przeczytaniu tego artykułu powinieneś umieć wdrożyć funkcje uwierzytelniania w swoim serwerze MCP zgodnie z najnowszą specyfikacją. Pamiętaj o kilku ważnych kwestiach: bezpiecznie waliduj tokeny, poprawnie konfiguruj metadane i dokładnie weryfikuj pole audience.

Jeśli tworzysz serwer MCP, wypróbuj bibliotekę MCP Auth. Implementuje ona wszystkie opisane tu funkcje i pozwala łatwo zintegrować obsługę uwierzytelniania.

W razie pytań zachęcam do dyskusji na GitHubie. Wspólnie rozwijajmy ekosystem MCP.