Jak napisać własny serwer MCP dla Claude Code

Claude Code

Jak napisać własny serwer MCP dla Claude Code

W skrócie

MCP, czyli Model Context Protocol, to standardowy sposób, w jaki Claude Code - narzędzie CLI od Anthropic do programowania z AI - rozmawia z zewnętrznymi narzędziami. Gotowych serwerów MCP jest sporo (do plików, do baz, do popularnych usług), ale prędzej czy później trafiasz na system, którego nikt jeszcze nie opakował: wewnętrzne API firmy, własny magazyn danych, jakieś specyficzne narzędzie. Wtedy piszesz własny serwer MCP. Brzmi poważnie, ale w praktyce to niewielki program, który wystawia kilka funkcji i mówi Claude Code, jak je wywołać.

Jak to wygląda w praktyce

Próbujesz opisać Claude Code słowami, gdzie leżą Twoje dane albo jak odpytać firmowe API, a narzędzie i tak zgaduje albo odpowiada z wiedzy ogólnej, bo nie ma jak sięgnąć do tego systemu. Podpięcie gotowego serwera nie wchodzi w grę, bo dla Twojego narzędzia po prostu żaden nie istnieje. Na liście narzędzi (widocznej po /mcp) nie ma nic, co dotykałoby Twojego systemu. Efekt: Claude Code potrafi czytać kod repozytorium, ale nie potrafi na przykład sprawdzić statusu zamówienia w Waszym wewnętrznym serwisie, bo nikt mu takiego kanału nie dał.

Dlaczego Claude Code tak działa

Claude Code z założenia nie ma wbudowanej wiedzy o Twoich prywatnych systemach - i to jest cecha, nie usterka. Zamiast zgadywać, korzysta z jasno zdefiniowanych narzędzi, które ktoś mu udostępnił przez protokół MCP. Serwer MCP to program, który ogłasza listę narzędzi (każde z nazwą, opisem i schematem argumentów) i potrafi je wykonać na żądanie. Claude Code łączy się z takim serwerem, pobiera listę narzędzi i dopiero wtedy może ich użyć. Dlatego wiedzy nie da się podpiąć samym zdaniem w czacie - trzeba wystawić serwer, który mówi tym samym językiem co narzędzie. Najprostszy wariant to serwer uruchamiany lokalnie jako proces potomny, komunikujący się przez standardowe wejście i wyjście (stdio) - Claude Code sam go wtedy uruchamia i zamyka razem z sesją.

Jak to rozwiązać krok po kroku

1. Wybierz język i sięgnij po oficjalny SDK do MCP - jest w wersji dla Pythona i dla TypeScriptu. SDK bierze na siebie protokół, więc piszesz tylko logikę swoich narzędzi, a nie obsługę komunikacji.
2. Zdefiniuj narzędzia, które serwer ma wystawiać. Każde z nich to funkcja z czytelną nazwą, krótkim opisem (to on mówi modelowi, kiedy narzędzia użyć) i opisem argumentów. Trzymaj się jednej, wąskiej odpowiedzialności na narzędzie.
3. W ciele każdej funkcji wpnij faktyczne działanie - zapytanie do bazy, wywołanie firmowego API, odczyt pliku. To jedyna część, którą naprawdę piszesz sam.
4. Uruchom serwer w trybie stdio, czyli tak, by czytał żądania ze standardowego wejścia i odpisywał na standardowe wyjście. Ten transport jest najprostszy dla serwerów lokalnych i nie wymaga otwierania żadnych portów.
5. Dodaj serwer do konfiguracji Claude Code. Dla zasięgu projektu utwórz w repozytorium plik .mcp.json z wpisem: nazwa serwera, command (czym go uruchomić, na przykład python albo npx) i args (argumenty startowe). Alternatywnie dodaj go poleceniem claude mcp add.
6. Sekrety (hasła, klucze API) przekaż przez sekcję env we wpisie serwera, odwołując się do zmiennych środowiskowych w postaci ${NAZWA}. Nie wpisuj poświadczeń na sztywno do pliku, który trafia do repozytorium.
7. Zrestartuj sesję Claude Code, żeby wczytał nową konfigurację, a następnie w rozmowie poproś o zadanie wymagające Twojego narzędzia i pozwól narzędziu je wywołać.

Jak sprawdzić, że zadziałało

Otwórz w sesji polecenie /mcp - Twój serwer powinien być na liście połączonych, a pod nim komplet narzędzi, które ogłosiłeś. Jeśli serwer się nie łączy, uruchom go ręcznie tą samą komendą co w konfiguracji i sprawdź, czy nie wypisuje błędu na starcie. Następnie zadaj Claude Code pytanie, na które potrafi odpowiedzieć tylko przy pomocy Twojego narzędzia (na przykład o dane z firmowego systemu) i obserwuj, czy narzędzie faktycznie wywołuje odpowiednią funkcję, a nie odpowiada ogólnikiem. Dobry dowód poprawnej integracji to konkretna odpowiedź oparta na danych zwróconych przez serwer, a nie na ogólnej wiedzy modelu.

Wróć do listy: 100 najczęstszych problemów z Claude Code

Szkolenie Claude Code - od zera do zespołu agentów AI -->

Szkolenie Claude Code - od zera do zespołu agentów AI

Tryb planowania, tryby uprawnień, komendy, MCP, hooki i systemy multi-agent - wszystko na żywym kodzie podczas trzydniowego szkolenia. Prowadzi Łukasz Matuszewski. Szkolenie ma terminy gwarantowane - odbędzie się niezależnie od liczby zgłoszeń.

Sprawdź szkolenie Claude Code

To szkolenie może być dofinansowane dla Ciebie z KFS lub BUR.

★★★★★Średnia ocena naszych szkoleń w Google: 5/5