Przejdź do głównej zawartości

Claude Code łączy się z serwerami MCP (Model Context Protocol) rejestrowanymi poleceniem claude mcp add w jednym z trzech zakresów: local, user lub project. Serwery projektowe trafiają do commitowanego pliku .mcp.json, który rozwija odwołania ${VAR}, więc sekrety nie lądują w gicie. Zanim zaufasz wynikom serwera, powinien przejść health check (sprawdzenie stanu) i skryptowy test wywołania narzędzia.

Ta strona jest dla programisty, który podłącza Claude Code do usług używanych na co dzień, i dla tech leada, który chce mieć te same serwery na komputerze każdego członka zespołu. Prosisz Claude Code o naprawę najczęstszego błędu z Sentry, a on odpowiada, że nie ma dostępu do Sentry. Podłączasz GitHub i tydzień później nikt nie wie, czy agent przeczytał log z CI, czy zgadywał. Podłączenie serwera to jedno polecenie. Reszta tej strony dotyczy tego, co serwer może robić i jak udowodnić, że naprawdę zadziałał.

  • Pierwszy serwer (Context7) podłączony i sprawdzony przez claude mcp list, /mcp oraz prompt, który wymusza prawdziwe wywołanie narzędzia.
  • Polecenia do skopiowania dla serwerów, od których zaczyna większość zespołów: GitHub, Sentry, Linear, Atlassian, Figma i baza danych tylko do odczytu.
  • Decyzję o zakresie (local, project lub user) i commitowany .mcp.json bez żadnych sekretów.
  • Reguły uprawnień, które nie pozwalają narzędziu MCP niczego zapisać bez pytania, oraz ustawienia, które chronią kontekst przed zalewem wyników.
  • Smoke test claude -p w trybie headless, który kończy się błędem, gdy wymagany serwer nie wystartował albo nie został wywołany.

Zanim zaczniesz, przejdź konfigurację Claude Code. Każde polecenie z tej strony sprawdziliśmy 26 września 2026 na Claude Code 2.1.283 (kanał latest; claude --version), z wyjątkiem fragmentów, które podają nowszą wersję lub datę 2026-10-12; te sprawdziliśmy ponownie na Claude Code 2.1.296 i na stronach Anthropic tego dnia.

Serwer MCP daje Claude Code dodatkowe narzędzia obok wbudowanych, takich jak Read, Edit i Bash. Każde narzędzie ma nazwę w postaci mcp__<serwer>__<narzędzie>, na przykład mcp__github__get_file_contents. Ty opisujesz zwykłym językiem, czego potrzebujesz, a Claude Code sam wybiera narzędzie.

TransportJak Claude Code do niego docieraDo czegoJak dodać
http (streamable HTTP)Przez URL, z OAuth albo nagłówkiemUsługi hostowane: GitHub, Sentry, Linear, Atlassian, Figmaclaude mcp add --transport http <nazwa> <url>
stdio (domyślny)Claude Code uruchamia lokalny procesBazy danych, lokalne narzędzia, wszystko z Dockera lub npxclaude mcp add <nazwa> -- <polecenie> [argumenty]

SSE jest przestarzały, więc dla usług, które oferują oba transporty, wybieraj http. Claude Code domyślnie negocjuje z bezpośrednimi serwerami HTTP protokół MCP 2026-07-28 (na wszystkich instalacjach od v2.1.274), a od v2.1.292 także z lokalnymi serwerami stdio, a od v2.1.295 z konektorami claude.ai na instalacjach, które nie pobierają flag funkcji (zmiana z v2.1.292 i domyślne zachowanie z v2.1.274 są na 2026-10-17 w obu kanałach; zmiana z v2.1.295 jest tylko w kanale latest; MCP_PROTOCOL_NEGOTIATION=legacy wyłącza to). Ma to znaczenie tylko wtedy, gdy starszy serwer zaczyna się dziwnie zachowywać; zobacz Gdy serwery MCP w Claude Code przestają działać. Sam protokół opisuje przegląd MCP.

Zacznij od Context7: nie wymaga konta, a jeden prompt pokazuje, czy odpowiedział.

  1. Dodaj serwer w terminalu, będąc w katalogu projektu. Wszystko po -- to polecenie, które uruchomi Claude Code:

    Okno terminala
    claude mcp add context7 -- npx -y @upstash/context7-mcp

    Claude Code wypisze Added stdio MCP server context7 ... to local config. Domyślny zakres to local, więc wpis trafia do ~/.claude.json pod ścieżką tego projektu i nikt inny go nie widzi.

  2. Sprawdź, czy serwer startuje. claude mcp list sprawdza stan każdego serwera, z którym wolno mu się połączyć; claude mcp get context7 pokazuje jeden:

    Okno terminala
    claude mcp list
    claude mcp get context7
  3. Uruchom claude i wpisz /mcp. Zobaczysz stan i narzędzia każdego serwera. /mcp reconnect context7 ponawia połączenie bez restartu sesji.

  4. Każ Claude Code wywołać narzędzie: wklej poniższy prompt do sesji i sprawdź, czy odpowiedź podaje identyfikator biblioteki z Context7 i cytuje fragment dokumentacji.

Prompt celowo żąda identyfikatora biblioteki i cytatu z dokumentacji. Odpowiedź bez nich pochodzi z danych treningowych modelu, a nie z serwera, i właśnie ten przypadek chcesz wykluczyć.

Podłącz serwery, od których zaczyna większość zespołów

Dział zatytułowany „Podłącz serwery, od których zaczyna większość zespołów”

Każda zakładka zawiera polecenie i to, na co trzeba uważać. W serwerach hostowanych z OAuth wpisz /mcp w sesji i wybierz serwer, żeby się zalogować, albo uruchom w terminalu claude mcp login <nazwa> (przez SSH dodaj --no-browser). Adresy URL sprawdziliśmy we wrześniu 2026 w rejestrze MCP i w README dostawców.

Oficjalny zdalny serwer GitHuba obsługuje PR-y, issues i logi z Actions. Claude Code wysyła w nagłówku fine-grained personal access token (PAT). Token trzymaj w powłoce, a w konfiguracji tylko nazwę zmiennej. Pojedyncze cudzysłowy nie pozwalają powłoce jej rozwinąć:

Okno terminala
export GITHUB_PAT=github_pat_... # in your shell profile, never in a file you commit
claude mcp add --transport http --scope project github https://api.githubcopilot.com/mcp/ \
-H 'Authorization: Bearer ${GITHUB_PAT}'

Wpis w .mcp.json zachowuje dosłowne ${GITHUB_PAT}, a Claude Code rozwija je przy starcie. Do samego triażu użyj https://api.githubcopilot.com/mcp/readonly, który nie udostępnia narzędzi zapisu. gh w Bash robi wiele z tego samego, zużywając mniej tokenów, więc wiele zespołów używa obu. Zestawy narzędzi i tryb lockdown: GitHub MCP.

Oficjalny serwer Slacka wymaga wcześniej zarejestrowanego klienta OAuth, więc instaluj go jako plugin slack@claude-plugins-official (/plugin w sesji), a nie gołym poleceniem claude mcp add. Resztę przeglądaj przez /plugin, a zanim dodasz więcej niż trzy serwery, porównaj je na stronie niezbędne serwery MCP.

Nie każda integracja potrzebuje serwera. Serwer MCP ma sens, gdy agent potrzebuje żywych danych albo działań w innym systemie: otwartego issue w Sentry, ticketu w Jirze, wiersza w bazie. Gdy chodzi o procedurę, którą agent ma wykonać, na przykład waszą checklistę wydania albo sposób pisania migracji, lżejszy jest skill: prawie nie zużywa kontekstu, dopóki nie zostanie użyty, i nie wymaga procesu ani tokena. Wielu dostawców wydaje oba w jednym pluginie, tak jak Figma powyżej. Drugą połowę tej decyzji opisuje strona Agent Skills.

Zakres wybierasz według tego, kto potrzebuje serwera i czyich poświadczeń on używa:

ZakresFlagaGdzie zapisanyWybierz, gdy
Local (domyślny)--scope local~/.claude.json, pod ścieżką tego projektuTestujesz serwer albo używa on twojego osobistego konta w jednym repozytorium
Project--scope project.mcp.json w katalogu głównym repozytorium, commitowanyPotrzebuje go każdy w tym repozytorium, a poświadczenia pochodzą z ${VAR} lub OAuth
User--scope user~/.claude.json, dla wszystkich projektówTo twoje osobiste narzędzie, które chcesz mieć wszędzie, na przykład Context7

Commitowany .mcp.json wygląda tak. Zawiera tylko adresy, polecenia i nazwy zmiennych:

{
"mcpServers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
},
"sentry": { "type": "http", "url": "https://mcp.sentry.dev/mcp" },
"context7": { "type": "stdio", "command": "npx", "args": ["-y", "@upstash/context7-mcp@4.1.1"] }
}
}

Wpis stdio ma przypiętą wersję (@upstash/context7-mcp 4.1.1 w npm, stan na 26 września 2026): to polecenie uruchamia każda osoba w zespole, więc niezablokowana wersja pakietu w npx to ryzyko w łańcuchu dostaw. ${VAR} i ${VAR:-domyślna} są rozwijane w command, args, env, url i headers. Wartości domyślnej używaj tylko dla danych niepoufnych, na przykład bazowego URL-a stagingu. Zmienne, których potrzebuje każdy serwer, opisz w CLAUDE.md albo w README.

Serwery projektowe nie startują, dopóki każda osoba ich nie zatwierdzi. claude mcp list pokazuje je jako Pending approval, a pierwsza interaktywna sesja claude w repozytorium pyta o zgodę. To zabezpieczenie: .mcp.json z niezaufanej gałęzi może uruchomić na twoim komputerze dowolne polecenie. Żeby z góry zatwierdzić wybrane serwery, wpisz je do enabledMcpjsonServers w ustawieniach; enableAllProjectMcpServers: true stosuj tylko w repozytoriach, które kontrolujesz.

Każdy serwer udostępnia modelowi swoje narzędzia, a narzędzie zapisu działa z pełnymi uprawnieniami swojego tokena. O tym, co dalej, decydują reguły uprawnień: reguła allow pozwala uruchomić narzędzie bez pytania, a reguła deny blokuje je w każdym trybie uprawnień, także w trybie auto. Zezwól na serwery tylko do odczytu i zablokuj nieodwracalne narzędzia. Reguły zespołu umieść w .claude/settings.json:

{
"permissions": {
"allow": ["mcp__context7", "mcp__sentry"],
"deny": ["mcp__github__merge_pull_request", "mcp__github__delete_file"]
}
}

mcp__context7 pasuje do wszystkich narzędzi serwera, a mcp__github__merge_pull_request do jednego. Prawdziwe nazwy narzędzi odczytaj z /mcp, zanim napiszesz regułę, bo literówka sprawia, że reguła nie pasuje do niczego.

Kontekst zużywają zarówno definicje narzędzi, jak i ich wyniki:

  • Wyszukiwanie narzędzi jest domyślnie włączone. Claude Code ładuje definicje narzędzi MCP na żądanie, a nie wszystkie naraz. ENABLE_TOOL_SEARCH=false ładuje wszystko od razu, a ENABLE_TOOL_SEARCH=auto:N przełącza na wyszukiwanie dopiero wtedy, gdy definicje przekroczą N% okna kontekstu. Jeśli ANTHROPIC_BASE_URL wskazuje na proxy, które nie jest hostem Anthropic, wersja 2.1.283 wyłącza wyszukiwanie narzędzi, chyba że ustawisz ENABLE_TOOL_SEARCH=true. To działa tylko wtedy, gdy proxy przekazuje bloki tool_reference.
  • Serwer może zrezygnować z odroczenia albo je wymusić. "alwaysLoad": true we wpisie serwera ładuje jego narzędzia od razu, niezależnie od ENABLE_TOOL_SEARCH, za cenę kontekstu w każdej turze. Od v2.1.287 (oba kanały wydań na 2026-10-12) "alwaysLoad": false trzyma wszystkie narzędzia tego serwera za wyszukiwaniem narzędzi, także te, które autor oznaczył do ładowania od razu (dokumentacja MCP w Claude Code, sprawdzona 2026-10-12).
  • Opisy są przycinane. Claude Code skraca opis każdego narzędzia i instrukcje każdego serwera, które wysyła od razu: domyślny limit wzrósł z 2048 do 4096 znaków w v2.1.296 (na 2026-10-12 tylko kanał latest), chociaż strona Anthropic o MCP nadal podawała 2048 na 2026-10-12. Opis, który model ładuje przez wyszukiwanie narzędzi, jest ucinany na 16 384 znakach od v2.1.295 (tylko latest; wcześniej 2048). CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH (v2.1.280 lub nowsza) ustawia limit dla każdego serwera. Jeśli piszesz serwer, najważniejszy szczegół umieść na początku.
  • Duże wyniki są przycinane. Pojedynczy wynik MCP jest domyślnie ograniczony do około 25 000 tokenów (wartość zapasowa w 2.1.283; może ją zastąpić wartość ustawiona po stronie serwera Anthropic, ale MAX_MCP_OUTPUT_TOKENS zawsze ma pierwszeństwo). Gdy potrzebujesz całego logu, podnieś limit dla jednej sesji: MAX_MCP_OUTPUT_TOKENS=50000 claude. Zwykle lepiej jednak poprosić serwer o mniej (zakres dat, LIMIT).
  • Bezczynne serwery są tanie, ale nie darmowe. /context pokazuje, ile w bieżącej sesji kosztują narzędzia MCP, a /mcp disable <serwer> wyłącza serwer w tym projekcie. Szerzej o kompromisach piszemy w tekście jak zmniejszyć koszt tokenów MCP.

Jak zweryfikować pracę z MCP bez czytania każdej linii?

Dział zatytułowany „Jak zweryfikować pracę z MCP bez czytania każdej linii?”

Serwer zmienia to, co agent wie, a nie to, jak sprawdzasz wynik. Zweryfikuj trzy rzeczy, w tej kolejności.

1. Serwer działa. claude mcp list pokazuje, czy każdy serwer jest połączony, czy nie udało się połączyć, czy wymaga logowania. Uruchamiaj to po wdrożeniu nowej osoby i po każdej aktualizacji Claude Code.

2. Narzędzie zostało wywołane. W trybie headless --output-format stream-json wypisuje po jednym zdarzeniu JSON w wierszu. Pierwsze zdarzenie ("subtype":"init") wymienia każdy serwer MCP z jego status, a każde wywołanie narzędzia pojawia się jako blok tool_use w wiadomości asystenta. Ten skrypt kończy się błędem, jeśli Context7 się nie połączył albo nie został wywołany. Uruchamiaj go z katalogu głównego repozytorium, na swoim komputerze albo w zadaniu CI, które wykonuje wyłącznie zaufany kod:

Okno terminala
claude -p "Use the context7 MCP server to resolve the library ID for React. Reply with the ID only." \
--mcp-config .mcp.json --strict-mcp-config \
--allowedTools "mcp__context7" \
--output-format stream-json --verbose > mcp-smoke.jsonl
jq -e 'select(.type=="system" and .subtype=="init")
| .mcp_servers[] | select(.name=="context7" and .status=="connected")' mcp-smoke.jsonl >/dev/null \
|| { echo "context7 did not connect"; exit 1; }
jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use") | .name' mcp-smoke.jsonl \
| grep -q '^mcp__context7__' && echo "context7 OK" || { echo "context7 NOT CALLED"; exit 1; }

--strict-mcp-config ładuje wyłącznie serwery z --mcp-config, więc wynik nie zależy od niczyjej osobistej konfiguracji. Startuje jednak każdy serwer z tego pliku, dlatego w CI wskaż osobny mcp-smoke.json z samymi testowanymi serwerami; pełny .mcp.json uruchomiłby też GitHub z nieustawionym ${GITHUB_PAT} i Sentry bez logowania OAuth. --allowedTools z góry zatwierdza ten jeden serwer, bo nikt nie odpowie na pytanie o uprawnienia. stream-json razem z -p wymaga --verbose. Nigdy nie uruchamiaj tego na pull requeście z niezaufanego forka, gdy w środowisku są sekrety: .mcp.json z takiej gałęzi uruchamia własne polecenia. Ten przypadek opisują model zagrożeń dla agentów i zabezpieczanie serwerów MCP.

3. Zmiana jest poprawna. Dokumentacja z Context7 ani stack trace z Sentry nie sprawiają, że kod jest dobry. O poprawności nadal rozstrzygają testy, type checker i linter oraz test, który nie przechodzi, napisany przed poprawką. Poproś o to wprost:

Recenzent, zwykle autor PR-a, a potem tech lead odpowiedzialny za .mcp.json, zatwierdza zmianę na podstawie dowodów: identyfikatora issue z Sentry, testu, który wcześniej nie przechodził, a teraz przechodzi, i zielonego zestawu testów w CI. Taki przegląd nie wymaga czytania diffu linia po linii.

ObjawPrawdopodobna przyczynaCo zrobić
claude mcp list pokazuje serwer zdalny jako Failed to connect z błędem ENOENTDodano go bez --transport http, więc stał się serwerem stdio z URL-em jako poleceniemclaude mcp remove <nazwa>, potem dodaj go ponownie z --transport http
Serwery projektowe mają status Pending approval i nigdy się nie łącząNikt nie zatwierdził .mcp.json w sesji interaktywnej albo ktoś odmówiłUruchom claude w repozytorium i zatwierdź; claude mcp reset-project-choices kasuje wcześniejsze decyzje
„Connection closed” dla serwera stdio na natywnym WindowsieWindows nie uruchamia npx bezpośrednioOpakuj polecenie: claude mcp add my-server -- cmd /c npx -y @some/package
Serwer jest na liście, ale w /mcp nie ma narzędziPolecenie nie działa poza Claude Code: brak npx w PATH, zatrzymany Docker albo ${VAR} nieustawiona w powłoce, z której uruchomiono claudeUruchom to samo polecenie w terminalu; wyeksportuj zmienne, potem /mcp reconnect <nazwa>
OAuth zwraca „does not support dynamic client registration”Serwer wymaga wcześniej zarejestrowanej aplikacji OAuthDodaj serwer ponownie z --client-id <id> --client-secret (Claude Code poprosi o sekret) i --callback-port, jeśli redirect URI jest stały
Wynik jest ucięty albo odrzucony jako za dużyDomyślny limit około 25 000 tokenówNajpierw zawęź zapytanie; w ostateczności ustaw MAX_MCP_OUTPUT_TOKENS dla tej sesji
Po dodaniu bramki LLM narzędzia MCP przestały się odnajdywaćWyszukiwanie narzędzi jest wyłączone przy ANTHROPIC_BASE_URL spoza AnthropicUstaw ENABLE_TOOL_SEARCH=true, jeśli bramka przekazuje bloki tool_reference; w przeciwnym razie ogranicz liczbę serwerów
Starszy samodzielnie hostowany serwer HTTP pada po aktualizacjiŹle obsługuje negocjację MCP 2026-07-28Ustaw MCP_PROTOCOL_NEGOTIATION=legacy na czas aktualizacji serwera; zobacz MCP 2026-07-28
Serwer na protokole 2025-11-25 przestał się łączyć po v2.1.287Claude Code odpowiada teraz na monity URL od takich serwerów, na przykład o logowanieDodaj "bareElicitationCapability": true do wpisu konfiguracji MCP tego serwera, jak podaje wpis changelogu 2.1.287
Kilka serwerów nie połączyło się albo wymaga logowania narazOsobny restart lub logowanie dla każdego serwera trwa długo/mcp reconnect all ponawia połączenie z każdym serwerem, który zawiódł lub wymaga uwierzytelnienia; w interaktywnym terminalu wymaga v2.1.284 lub nowszej, a starsze wersje wypisują MCP server "all" not found
Wywołanie narzędzia zatrzymuje monit o ponowne zalogowanieSerwer poprosił w trakcie wywołania o szerszy zakres OAuth (v2.1.288, oba kanały wydań na 2026-10-17)Zaakceptuj monit o ponowne uwierzytelnienie albo uwierzytelnij serwer ponownie w /mcp
Pierwszy start przekracza limit czasu, bo npx pobiera pakietWolna pierwsza instalacjaPobierz pakiet raz w terminalu albo zwiększ MCP_TIMEOUT (w milisekundach)

Problemy z połączeniem MCP opisują debugowanie na poziomie transportu, wspólne dla wszystkich klientów, a claude --debug "mcp" loguje próby połączenia.

Czy ten artykuł Ci pomógł?

Jedno kliknięcie, bez logowania.

wcale bardzo