Konfiguracja serwerów MCP w Claude Code
ENClaude 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ł.
Co zyskasz dzięki konfiguracji MCP w Claude Code
Dział zatytułowany „Co zyskasz dzięki konfiguracji MCP w Claude Code”- Pierwszy serwer (Context7) podłączony i sprawdzony przez
claude mcp list,/mcporaz 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.jsonbez ż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 -pw 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.
Jak Claude Code łączy się z serwerem MCP?
Dział zatytułowany „Jak Claude Code łączy się z serwerem MCP?”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.
| Transport | Jak Claude Code do niego dociera | Do czego | Jak dodać |
|---|---|---|---|
http (streamable HTTP) | Przez URL, z OAuth albo nagłówkiem | Usługi hostowane: GitHub, Sentry, Linear, Atlassian, Figma | claude mcp add --transport http <nazwa> <url> |
stdio (domyślny) | Claude Code uruchamia lokalny proces | Bazy danych, lokalne narzędzia, wszystko z Dockera lub npx | claude 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.
Dodaj pierwszy serwer i udowodnij, że działa
Dział zatytułowany „Dodaj pierwszy serwer i udowodnij, że działa”Zacznij od Context7: nie wymaga konta, a jeden prompt pokazuje, czy odpowiedział.
-
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-mcpClaude Code wypisze
Added stdio MCP server context7 ... to local config. Domyślny zakres to local, więc wpis trafia do~/.claude.jsonpod ścieżką tego projektu i nikt inny go nie widzi. -
Sprawdź, czy serwer startuje.
claude mcp listsprawdza stan każdego serwera, z którym wolno mu się połączyć;claude mcp get context7pokazuje jeden:Okno terminala claude mcp listclaude mcp get context7 -
Uruchom
claudei wpisz/mcp. Zobaczysz stan i narzędzia każdego serwera./mcp reconnect context7ponawia połączenie bez restartu sesji. -
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ąć:
export GITHUB_PAT=github_pat_... # in your shell profile, never in a file you commitclaude 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.
Issues, zdarzenia i trace’y z hostowanego serwera Sentry, z OAuth. To przykład z samego claude mcp add --help:
claude mcp add --transport http sentry https://mcp.sentry.dev/mcpPotem /mcp → sentry → logowanie. Jeśli zamiast OAuth używasz tokena, Sentry oczekuje nagłówka Authorization: Sentry-Bearer <token>, a nie Bearer. Pakiet stdio @sentry/mcp-server jest przeznaczony dla Sentry hostowanego samodzielnie.
Oba to serwery hostowane z OAuth:
claude mcp add --transport http linear https://mcp.linear.app/mcpclaude mcp add --transport http atlassian https://mcp.atlassian.com/v2/mcpAtlassian przeniósł serwer na /v2/mcp; stary endpoint /v1/sse przestał działać po 30 czerwca 2026. Połączenie musi dopuścić administrator Atlassiana, a narzędzia Jira Service Management wymagają tokena API. Szczegóły: Atlassian Rovo MCP.
Kontekst projektów i mapowania Code Connect z hostowanego serwera Figmy. Oficjalny plugin łączy serwer ze skillami Figmy:
claude plugin install figma@claude-plugins-official# or the server alone:claude mcp add --transport http figma https://mcp.figma.com/mcpFigma ogranicza plany Starter oraz miejsca View i Collab do najwyżej 6 wywołań narzędzi miesięcznie (Figma, stan na wrzesień 2026), więc osoba, która zamienia projekty na kod, potrzebuje miejsca Dev albo Full. Zobacz Figma i MCP dla design systemów.
DBHub (npm @bytebase/dbhub, 1.3.1 według stanu na 26 września 2026) to jeden serwer stdio dla Postgresa, MySQL, SQL Servera, MariaDB, Oracle i SQLite. Przypnij wersję, a DSN czytaj ze zmiennej środowiskowej:
claude mcp add --scope project db -- \ npx -y @bytebase/dbhub@1.3.1 --transport stdio --dsn '${DATABASE_URL}'Niech DATABASE_URL wskazuje na rolę tylko do odczytu w lokalnej lub stagingowej kopii bazy. Narzędzie, które wykonuje SQL, wykonuje go z uprawnieniami roli, a prompt wstrzyknięty przez wiersz tabeli albo ticket może zażądać zapisu. Więcej serwerów i zabezpieczeń: serwery MCP dla baz danych.
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 local, project czy user?
Dział zatytułowany „Zakres local, project czy user?”Zakres wybierasz według tego, kto potrzebuje serwera i czyich poświadczeń on używa:
| Zakres | Flaga | Gdzie zapisany | Wybierz, gdy |
|---|---|---|---|
| Local (domyślny) | --scope local | ~/.claude.json, pod ścieżką tego projektu | Testujesz serwer albo używa on twojego osobistego konta w jednym repozytorium |
| Project | --scope project | .mcp.json w katalogu głównym repozytorium, commitowany | Potrzebuje go każdy w tym repozytorium, a poświadczenia pochodzą z ${VAR} lub OAuth |
| User | --scope user | ~/.claude.json, dla wszystkich projektów | To 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.
Kontroluj, co serwer MCP może robić i ile kosztuje
Dział zatytułowany „Kontroluj, co serwer MCP może robić i ile kosztuje”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, aENABLE_TOOL_SEARCH=auto:Nprzełącza na wyszukiwanie dopiero wtedy, gdy definicje przekroczą N% okna kontekstu. JeśliANTHROPIC_BASE_URLwskazuje na proxy, które nie jest hostem Anthropic, wersja 2.1.283 wyłącza wyszukiwanie narzędzi, chyba że ustawiszENABLE_TOOL_SEARCH=true. To działa tylko wtedy, gdy proxy przekazuje blokitool_reference. - Serwer może zrezygnować z odroczenia albo je wymusić.
"alwaysLoad": truewe wpisie serwera ładuje jego narzędzia od razu, niezależnie odENABLE_TOOL_SEARCH, za cenę kontekstu w każdej turze. Od v2.1.287 (oba kanały wydań na 2026-10-12)"alwaysLoad": falsetrzyma 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 (tylkolatest; 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_TOKENSzawsze 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.
/contextpokazuje, 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:
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.
Gdy serwery MCP w Claude Code przestają działać
Dział zatytułowany „Gdy serwery MCP w Claude Code przestają działać”| Objaw | Prawdopodobna przyczyna | Co zrobić |
|---|---|---|
claude mcp list pokazuje serwer zdalny jako Failed to connect z błędem ENOENT | Dodano go bez --transport http, więc stał się serwerem stdio z URL-em jako poleceniem | claude 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 Windowsie | Windows nie uruchamia npx bezpośrednio | Opakuj polecenie: claude mcp add my-server -- cmd /c npx -y @some/package |
Serwer jest na liście, ale w /mcp nie ma narzędzi | Polecenie nie działa poza Claude Code: brak npx w PATH, zatrzymany Docker albo ${VAR} nieustawiona w powłoce, z której uruchomiono claude | Uruchom 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 OAuth | Dodaj 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ży | Domyślny limit około 25 000 tokenów | Najpierw 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 Anthropic | Ustaw 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-28 | Ustaw 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.287 | Claude Code odpowiada teraz na monity URL od takich serwerów, na przykład o logowanie | Dodaj "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 naraz | Osobny 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 zalogowanie | Serwer 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 pakiet | Wolna pierwsza instalacja | Pobierz 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.
Co dalej z MCP w Claude Code
Dział zatytułowany „Co dalej z MCP w Claude Code”Czy ten artykuł Ci pomógł?
Jedno kliknięcie, bez logowania.
Co z tym zrobisz?
Jak się czytało?
Co przeszkadzało? Możesz zaznaczyć kilka
Twoja rola?
Dzięki. Czytam każdą odpowiedź. Michał Jaskólski
Pomógł Ci ten artykuł?
Każde to jedno kliknięcie. Zamknij, kiedy chcesz.
bez logowania