Astro + AI: budowanie stron z Claude Code i Astro Docs MCP (konfiguracja krok po kroku) 

Astro ma własny serwer MCP dla dokumentacji. To nie jest wtyczka do Astro i nie pakiet do instalacji przez npm. To zdalny serwer pod adresem https://mcp.docs.astro.build/mcp, który podłączasz do Claude Code jednym poleceniem, a model zacznie czytać aktualną dokumentację Astro zamiast zgadywać API sprzed roku.

Do tej pory był to problem cichy. Model pamiętał, że w Astro jest getStaticPaths, content collections i wyspy z Reacta, więc kod wyglądał poprawnie, a przy wdrożeniu coś nie działało. Metoda, która przed rokiem była poprawna, dziś nie istnieje. Stracisz dwadzieścia minut na debugowanie metody, której już nie ma w kodzie źródłowym. Serwer dokumentacji nie naprawia wiedzy modelu. On sprawia, że model nie musi jej mieć.

Poniżej pełna konfiguracja krok po kroku, razem z miejscami, w których instrukcje z blogów są po prostu nieaktualne.

Czym jest Astro Docs MCP

MCP, czyli Model Context Protocol, to sposób na podłączenie modelu do zewnętrznego źródła danych. W uproszczeniu: model dostaje zestaw narzędzi, a serwer po drugiej stronie odpowiada na ich wywołania. Zamiast wklejać do czatu fragment dokumentacji, wpisujesz nazwę serwera i pytasz wprost.

Astro Docs MCP działa inaczej niż większość serwerów MCP. Nie instalujesz niczego lokalnie. Repozytorium mówi o tym wprost: serwer jest zdalny i nie wymaga instalacji na twojej maszynie. Nie ma pakietu npm, który trzeba dorzucić do projektu, nie ma procesu, który startuje przy każdej sesji.

Parametry, które podaje dokumentacja projektu:

• nazwa wyświetlana: Astro Docs
• adres: https://mcp.docs.astro.build/mcp
• transport: HTTP, czyli nowy wariant streamable HTTP

Ten ostatni punkt ma znaczenie praktyczne. Część narzędzi obsługuje wyłącznie starszy transport SSE i nie dogada się z tym serwerem. Claude Code nie ma tego problemu, bo radzi sobie z HTTP. Ale jeśli planujesz używać tego samego serwera w Windsurfie, doczytaj sekcję o innych edytorach niżej.

Dla porządku: MCP to warstwa protokołu, a nie usługa. Serwer dokumentacyjny dla Astro jest jednym z wielu, a każdy projekt ma taki własny albo korzysta z cudzego. Jak wygląda serwer napisany od zera, opisałem osobno przy własnym serwerze MCP w Pythonie. Ten z dokumentacją jest rzadszy, bo dokumentujesz cudzy produkt, a nie swój.

Instalacja w Claude Code, cztery kroki

Krok 0 - terminal w katalogu projektu

Claude Code musi być zainstalowany i zalogowany, a terminal otwarty w katalogu projektu. Pusty katalog też wystarczy. Na macOS i Linuksie instalacja wygląda tak:

curl -fsSL https://claude.ai/install.sh | bash

Na Windowsie PowerShell wystarczy:

irm https://claude.ai/install.ps1 | iex

Instalacja przez npm działa, ale jest oznaczona jako przestarzała. Przy Astro Docs MCP nie potrzebujesz w ogóle Node.js, bo nic lokalnie nie uruchamiasz. Wymóg Node.js 18 lub nowszego dotyczy serwerów MCP odpalanych przez npx, a to inny przypadek.

Krok 1 - rejestracja serwera

Wklej w terminalu dokładnie to polecenie:

claude mcp add --transport http " Astro docs " https://mcp.docs.astro.build/mcp

Spacje wewnątrz cudzysłowu są takie w dokumentacji projektu i takie też zostały tutaj. Nazwa serwera wygląda dziwnie, ale działa.

Polecenie uruchamiasz w terminalu, a nie wewnątrz sesji Claude Code. Konfigurujesz serwer, zanim zaczniesz rozmowę.

Krok 2 - sprawdzenie, czy serwer się połączył

claude mcp list

Szukasz statusu Connected. Przy serwerze, który nie wymaga logowania, to wszystko. Jeśli wiersz wygląda inaczej, sekcja o diagnostyce niżej wyjaśnia, co znaczą poszczególne statusy.

Krok 3 - pierwsze zapytanie

Uruchom Claude Code w katalogu projektu i zapytaj po imieniu serwera:

claude
/ Uzyj serwera Astro docs i znajdz, jak zdefiniowac schemat w content collections

Nazwanie serwera w prompcie nie jest konieczne. Model zwykle sam sięga po właściwe narzędzie. Ale w pierwszej sesji warto to zrobić, żeby zobaczyć w wyjściu Claude wywołanie narzędzia z nazwą serwera. To jedyny sposób, żeby odróżnić odpowiedź z MCP od odpowiedzi z wbudowanej wiedzy modelu albo z pobrania strony przez WebFetch.

Przy pierwszym wywołaniu Claude Code poprosi o zgodę. Zatwierdzasz i patrzysz na nazwę serwera przy wywołaniu narzędzia. Właśnie to potwierdza, że odpowiedź przyszła z dokumentacji, a nie z głowy modelu.

Gdzie Claude Code trzyma tę konfigurację

Tu najczęściej kończy się pierwsza frustracja, bo wiele poradników podaje złe ścieżki do plików. Konfiguracja serwerów MCP leży w dwóch plikach, nie w settings.json. Wpis w ~/.claude/settings.json Claude Code przy MCP po prostu nie czyta.

Trzy zakresy wyglądają tak:

• local (domyślny) - wpis w pliku ~/.claude.json, przy projekcie, w którym dodałeś serwer. Widzisz go tylko ty, tylko w tym projekcie.
• project - wpis w pliku .mcp.json w katalogu głównym projektu. Ten plik commitujesz do repozytorium i każdy, kto sklonuje projekt, dostaje serwer. Przy pierwszym uruchomieniu Claude Code pyta o zatwierdzenie.
• user - wpis w pliku ~/.claude.json, tym razem pod kluczem mcpServers. Działa we wszystkich twoich projektach, nadal tylko dla ciebie.

Dlaczego polecenie z dokumentacji Astro ląduje w zakresie local

Dokumentacja Astro podaje komendę bez flagi --scope. Każda komenda claude mcp add bez tej flagi zapisuje się w zakresie local. Czyli po skopiowaniu instrukcji wprost serwer działa tylko w tym jednym projekcie, w którym go dodałeś.

Jeśli zespół ma pracować na tym samym repozytorium, dodaj flagę:

claude mcp add --scope project --transport http " Astro docs " https://mcp.docs.astro.build/mcp

Zakres jest stały po dodaniu serwera. Nie da się go zmienić edycją pliku albo komendą. Zmiana zakresu to usunięcie wpisu i dodanie go od nowa w docelowym zakresie:

claude mcp remove " Astro docs "
claude mcp add --scope project --transport http " Astro docs " https://mcp.docs.astro.build/mcp

Jeśli ta sama nazwa serwera pojawi się w dwóch zakresach z różnymi adresami, Claude Code ostrzega o konflikcie. Wtedy przy usuwaniu musisz podać zakres jawnie, czyli dodać --scope local albo --scope project.

Zmiana pliku .mcp.json wymaga restartu sesji

To drugie miejsce, gdzie ludzie tracą czas. Claude Code czyta plik .mcp.json przy starcie sesji. Edytujesz plik, patrzysz na ekran, a zmiana nie działa, bo sesja wciąż trzyma starą konfigurację w pamięci.

Zapisujesz plik, wychodzisz z sesji, uruchamiasz Claude Code od nowa. Dopiero wtedy zmiana jest widoczna.

Jest jeszcze niuans, o którym mało kto pisze. Plik konfiguracyjny i połączenie z serwerem to dwie osobne rzeczy. W aktualnych wersjach Claude Code ma mechanizm cache odkrywania, więc zamiast łączyć się z serwerem HTTP na starcie, może pokazać status w stylu „cached 2h ago, łączy się przy pierwszym użyciu”. Narzędzia są dostępne od pierwszej wiadomości, nie musisz nic robić. Ten cache jest domyślnie wyłączony, dopóki dla twojego konta go nie włączą, a steruje się zmienną MCP_DISCOVERY_CACHE.

Kiedy połączenie nie działa

Statusy z claude mcp list są konkretne i każdy coś oznacza. Na konsoli Windows 10 zamiast znaków statusu zobaczysz ich uproszczone wersje, ale treść komunikatu zostaje.

Lista serwerów jest pusta

Trzy możliwości. Po pierwsze, dodałeś serwer w innym projekcie i uruchomiłeś Claude Code w tym. Serwery z zakresu local są przywiązane do katalogu, w którym je dodano, czyli do katalogu głównego repozytorium albo do dokładnej ścieżki, jeśli nie był to repozytorium git.

Po drugie, wpisałeś serwer w plik, którego Claude Code nie czyta, na przykład w ~/.claude/settings.json.

Po trzecie, wpis w .mcp.json jest zepsuty składniowo. Claude Code pomija wtedy wadliwy wpis i wczytuje resztę, a w powłoce pokazuje ostrzeżenie o parsowaniu z nazwą problematycznego pola. Zajrzyj na wyjście z claude mcp list uruchomionego w terminalu, nie z wnętrza sesji.

Failed to connect i Connection error

Od wersji 2.1.219 komenda claude mcp get pokazuje kod HTTP i treść błędu, którą zwrócił serwer. To najszybsza droga do odpowiedzi, bo komunikat zwykle wprost nazywa problem, na przykład brakujący nagłówek albo odrzucony token. Status Connection error nie niesie szczegółów w żadnej wersji.

Adres 404 Claude Code pokazuje jako „endpoint nie znaleziony”. Wtedy claude mcp get wypisuje pełny adres, którego używasz. Warto też sprawdzić osiągalność z własnej maszyny:

curl -I https://mcp.docs.astro.build/mcp

Odpowiedź 404 lub 405 oznacza, że serwer żyje. Wiele punktów MCP odpowiada wyłącznie na żądania POST, więc test HEAD nie musi zwrócić 200 i to wcale nie oznacza awarii. Brak odpowiedzi w ogóle oznacza zły adres albo problem z siecią.

Serwer się łączy, ale nie ma narzędzi

Status w stylu „połączone, pobranie narzędzi nie powiodło się” oznacza, że serwer odpowiedział, ale nie zarejestrował żadnego narzędzia. Przy serwerach z kluczem API najczęściej brakuje zmiennej środowiskowej. Dla Astro Docs MCP to nie dotyczy, bo serwer działa bez uwierzytelniania i nie potrzebuje żadnych sekretów.

Do diagnostyki, gdy narzędzia się nie pojawiają mimo poprawnego połączenia, jest jeszcze flaga --mcp-debug.

Połączenie z innymi edytorami

Ten sam serwer działa poza Claude Code, bo to zwykły punkt HTTP. Dokumentacja podaje konfigurację dla kilku narzędzi.

Claude.ai i Claude Desktop - w ustawieniach konektorów wybierz dodanie własnego konektora, nazwij go Astro Docs i podaj adres https://mcp.docs.astro.build/mcp. To ścieżka dla kogoś, kto nie ma terminala. Konektory dodane w claude.ai wczytują się też w CLI po zalogowaniu na to samo konto.

Cursor i VS Code - dokumentacja podaje linki instalacyjne, których nie da się kliknąć bezpośrednio z GitHuba. Otwórz je w przeglądarce, a narzędzie doinstaluje serwer.

Windsurf - według dokumentacji projektu, od lipca 2025 nie obsługuje transportu streamable HTTP, więc potrzebny jest lokalny proxy:

{
  "mcpServers": {
    "Astro docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]
    }
  }
}

To jedyny przypadek, w którym przy tym serwerze pojawia się npx. Uwaga na to, że w tym wpisie nie ma pola type, bo to lokalny proces proxy, a nie połączenie HTTP.

ChatGPT - według dokumentacji obsługa MCP, tam określana jako Custom Connectors, była dostępna dla planów Pro, Team i Enterprise, a sama procedura dodania była skomplikowana.

Co dokładnie dostajesz, a czego nie ma w dokumentacji serwera

Tu warto być precyzyjnym, bo opisy w sieci rozjeżdżają się z rzeczywistością.

Oficjalne repozytorium projektu opisuje serwer jednym zdaniem: pozwala narzędziom AI, takim jak Cursor, VS Code, Claude, ChatGPT i Windsurf, sięgać po najnowszą dokumentację Astro. Nie podaje liczby ani nazw udostępnianych narzędzi. Nie ma listy, nie ma changelogu, nie ma numeru wersji, nie ma informacji o limitach zapytań ani o kosztach.

Jeśli szukasz w internecie liczby narzędzi udostępnianych przez Astro Docs MCP, nie znajdziesz jej w źródłach. Wszystkie konkretne liczby, które krążą przy innych serwerach, dotyczą innych serwerów.

Dokumentacja Astro dla projektu sama serwera nie opisuje. Strona „Getting started” nie wspomina ani MCP, ani Claude Code. Jest w menu pozycja „Build with AI”, ale dokumentacja serwera żyje w osobnym repozytorium organizacji, nie w głównym manualu. To drugi powód, żeby traktować repozytorium serwera jako jedyne wiarygodne źródło.

Bezpieczeństwo: dlaczego plik konfiguracji jest celem

Serwer dokumentacji nie ma kluczy API i nie prosi o uprawnienia. Nie zmienia to faktu, że plik, w którym siedzi konfiguracja, jest atrakcyjnym celem.

Badacze z firmy Mitiga Labs opisali w maju 2026 atak łańcuchowy na plik konfiguracji Claude Code. Mechanizm wygląda tak: szkodliwy pakiet npm z hookiem postinstall modyfikuje wpis serwera MCP we pliku ~/.claude.json i przestawia jego adres na własny proxy. Przy kolejnym odświeżeniu sesji MCP token przechodzi przez infrastrukturę atakującego. Hook działa przy każdym uruchomieniu Claude Code, więc nawet poprawienie adresu ręcznie niczego nie zmienia, bo następny start znów go nadpisuje.

Badacze wskazują cztery cechy, które czynią taki token celem: jest trwały między sesjami, ma szeroki zakres, jest zapisany zwykłym tekstem w tym samym pliku co flagi decydujące o tym, czy Claude Code pyta o zgodę na uruchomienie poleceń, i jest nieodróżnialny dla dostawcy API od tokenu z autoryzowanej maszyny. Zgłoszenie trafiło do Anthropic 10 kwietnia 2026, a odpowiedź z 12 kwietnia brzmiała, że to poza zakresem zgłoszenia, bo przy dostępie do wykonywania kodu wiele jest możliwe.

Przy Astro Docs MCP sam ten scenariusz oznacza mniej, bo serwer nie uwierzytelnia i nie przechowuje tokenu. Ale ten sam plik trzyma inne serwery, często z kluczami do firmowych narzędzi, i one są realnym celem.

Osobno ostrzeżenie z oficjalnej dokumentacji Claude Code: serwery pobierające treści z zewnątrz są wektorem ataku prompt injection. Dokumentację traktuj jako dane, a nie jako instrukcje. Dla Astro Docs MCP ryzyko jest niskie, bo to twoja własna dokumentacja projektu, ale zasada dotyczy każdego serwera MCP, który czyta cudze strony.

Praktyczne wnioski, które zostają z tego artykułu: przed zatwierdzeniem serwera z pliku .mcp.json sprawdź, co on robi, bo sklonowane repozytorium nie może zatwierdzić własnych serwerów bez twojej zgody. Trzymaj sekrety poza plikiem projektu i odwołuj się do zmiennych środowiskowych. Usuwaj serwery, których nie używasz, bo każdy podłączony serwer zajmuje miejsce w oknie kontekstu każdej sesji.

Gdzie kończy się MCP, a zaczyna się CLAUDE.md

Te dwie rzeczy nie konkurują. MCP dostarcza aktualne dane. Plik CLAUDE.md mówi modelowi, kiedy ma po niego sięgnąć.

Oficjalna dokumentacja opisuje to tak: plik CLAUDE.md włącza się do promptu systemowego przy każdej rozmowie, więc powinien być zwięzły. Praktyka jest taka, żeby dopisać w nim krótki blok informujący, których serwerów używać do czego, i zostawić resztę serwerowi. Wtedy przestajesz wpisywać nazwę serwera ręcznie do każdego pytania. Z tym samym podejściem pracuję przy promptach do Claude Code i Cursora: plik opisuje reguły projektu, a przykłady pytań trzymam osobno.

Dla projektu Astro taki blok wygląda prosto: do czego sięgasz, gdy pytasz o API Astro, oraz że przed wdrożeniem weryfikujesz wersję w package.json. Krótko, bez opisu każdego narzędzia z osobna.

Serwer dokumentacji nie zastąpi testów

MCP daje modelowi dostęp do dokumentacji, a dokumentacja opisuje API, nie zachowanie twojego kodu. Nie zna ustawień twojego adaptera, nie wie, że trzecia integracja ma buga w wersji 3.2, i nie sprawdzi, czy build przechodzi.

Użyteczny układ wygląda tak: serwer dokumentacji odpowiada na pytania o to, jak coś zbudować, Claude Code pisze kod, a testy i build mówią, czy działa. Trzeci element nadal jest obowiązkowy, bo dokumentacja i wdrożenie rozjeżdżają się szybciej niż ktokolwiek z nas się spodziewa.