Serwery MCP i Claude Code: praktyczny przewodnik po integracji i tworzeniu

Claude Code „z pudełka” potrafi już czytać lokalne pliki, wykonywać komendy w terminalu oraz edytować kod źródłowy projektu. Jednak w rzeczywistych zadaniach deweloperskich często okazuje się to niewystarczające: pojawia się potrzeba pozyskania danych z bazy PostgreSQL, sprawdzenia otwartych Pull Requestów na GitHubie, pobrania aktualnej dokumentacji z chmury czy wysłania zapytania do wewnętrznego API korporacyjnego.

Właśnie aby rozwiązać ten problem, powstał Model Context Protocol (MCP) – otwarty standard, który przekształca Claude Code ze zwykłego lokalnego asystenta w pełnoprawne centrum orkiestracji zewnętrznych systemów i usług.

W tym praktycznym poradniku omówimy architekturę MCP, nauczymy się podłączać oficjalne gotowe serwery, przeanalizujemy tworzenie własnego serwera w TypeScript oraz utrwalimy umiejętności na przykładzie realnych zadań praktycznych.

1. Czym jest serwer MCP

Model Context Protocol (MCP) to otwarty protokół komunikacyjny opracowany przez firmę Anthropic, standaryzujący interakcję między modelami językowymi (LLM) a zewnętrznymi narzędziami lub źródłami danych.

Zamiast pisać osobne, unikalne pluginy dla każdej usługi, MCP wprowadza jednolity interfejs klient-serwer.

Każdy serwer MCP udostępnia modelowi trzy podstawowe prymitywy:

• Tools (Narzędzia) – funkcje wykonywalne z typowaną schemą JSON parametrów, które Claude Code może samodzielnie wywoływać podczas rozwiązywania zadania (np. create_issue, execute_query).
• Resources (Zasoby) – pasywne dane lub schematy, które asystent może odczytywać jako kontekst wejściowy (pliki, schematy DB, logi).
• Prompts (Szablony promptów) – gotowe scenariusze kontekstowe, upraszczające wykonanie typowych, powtarzalnych zadań.

Porównanie możliwości Claude Code

2. Architektura i zasada działania MCP

Architektura interakcji opiera się na standardowym protokole JSON-RPC 2.0. W większości scenariuszy lokalnych komunikacja odbywa się przez standardowe strumienie wejścia/wyjścia (stdio), a dla zdalnych serwerów – przez Server-Sent Events (SSE) lub HTTP.

Krok po kroku: cykl życia zapytania

1. Inicjalizacja i Handshake: Przy uruchomieniu sesji Claude Code odczytuje plik konfiguracyjny, startuje wskazane procesy serwerów i żąda listy obsługiwanych narzędzi (tools/list).
2. Publikacja możliwości: Każdy serwer MCP zwraca listę swoich metod wraz ze schemami JSON parametrów oraz szczegółowym opisem przeznaczenia.
3. Ocena intencji: Gdy stawiasz zadanie w języku naturalnym, Claude porównuje Twoje zapytanie z dostępnymi narzędziami.
4. Wywołanie narzędzia: Jeśli zadanie wymaga danych zewnętrznych, model wysyła ustrukturyzowane zapytanie tools/call do serwera z walidowanymi argumentami.
5. Wykonanie po stronie serwera: Serwer łączy się z zewnętrznym API, bazą danych lub dyskiem i zwraca wynik do klienta.
6. Generowanie odpowiedzi: Po otrzymaniu surowych danych Claude interpretuje je i dostarcza Ci finalną, ustrukturyzowaną odpowiedź.

3. Jak podłączyć serwer MCP do Claude Code

Podłączanie serwerów odbywa się przez konfigurację JSON w bloku mcpServers. Claude Code obsługuje dwa poziomy konfiguracji:

1. Konfiguracja projektu (.claude/settings.json) – dotyczy wyłącznie bieżącego katalogu i może być zapisana w repozytorium dla całego zespołu.
2. Konfiguracja globalna (~/.claude/settings.json) – dostępna dla wszystkich projektów bieżącego użytkownika na komputerze.

json
Kopiuj
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/mcp-filesystem",
        "./docs"
      ]
    }
  }
}

Struktura parametrów konfiguracyjnych

Każdy wpis serwera w sekcji mcpServers składa się z trzech kluczowych pól:

4. Katalog gotowych serwerów MCP

Anthropic oraz społeczność open-source stworzyły gotowe serwery dla najpopularniejszych narzędzi. Nie musisz pisać kodu od zera – wystarczy podłączyć odpowiedni pakiet npm lub python.

1. Serwer Filesystem

Udostępnia Claude Code dostęp do katalogów poza bieżącym repozytorium (np. do globalnego folderu z dokumentacją lub notatkami Obsidian).

2. Serwer GitHub

Pozwala asystentowi bezpośrednio pracować z repozytoriami organizacji: czytać issues, zostawiać komentarze do PR i sprawdzać status pipeline’ów.

3. Serwer PostgreSQL

Daje możliwość wykonywania przez Claude zapytań analitycznych lub diagnostycznych bezpośrednio do Twojej lokalnej lub zdalnej bazy danych.

4. Serwer Brave Search

Integruje silnik wyszukiwania webowego, pozwalając asystentowi znajdować świeżą dokumentację, rozwiązania niedawno zgłoszonych bugów lub zmiany w bibliotekach.

5. Jak Claude Code wykorzystuje MCP w dialogu

Po dodaniu serwera do konfiguracji nie musisz wpisywać specjalnych komend ani prefiksów. Claude Code analizuje Twoje zapytanie w języku naturalnym i samodzielnie decyduje, kiedy sięgnąć po narzędzie.

Przykład scenariusza: praca z GitHub

Zapytanie użytkownika:

„Sprawdź, jakie otwarte issues są przypisane do mnie w repozytorium acme/platform i wypisz krótką listę najważniejszych.”

Wewnętrzny proces Claude Code:

1. Model rozpoznaje, że lokalne pliki nie wystarczą do udzielenia odpowiedzi.
2. Formułuje wywołanie mcp__github__search_issues z filtrami repo:acme/platform state:open assignee:@me.
3. Otrzymuje ustrukturyzowaną odpowiedź JSON od serwera GitHub.
4. Formatuje odpowiedź w przystępnej formie.

6. Tworzenie własnego serwera MCP w TypeScript

Jeśli gotowe rozwiązania nie wystarczają i potrzebujesz specyficznego narzędzia pod logikę biznesową lub wewnętrzne mikrousługi, serwer MCP można napisać samodzielnie w kilka minut przy użyciu oficjalnego SDK @modelcontextprotocol/sdk.

Krok 1. Inicjalizacja i instalacja zależności

Utwórz osobny katalog i zainstaluj biblioteki:

Krok 2. Implementacja serwera (server.ts)

Stwórz plik server.ts z definicją serwera i niestandardowego narzędzia:

Krok 3. Podłączenie serwera do Claude Code

Dodaj utworzony serwer do .claude/settings.json swojego projektu:

7. Bezpieczeństwo i izolacja przy pracy z MCP

MCP znacząco zwiększa autonomię Claude Code, ale daje kodowi możliwość interakcji z Twoim systemem operacyjnym i usługami zewnętrznymi. Aby zachować bezpieczeństwo środowiska pracy, przestrzegaj następujących zasad:

1. Serwer działa z Twoimi uprawnieniami systemowymi

Serwer MCP działa w kontekście bieżącego użytkownika systemu operacyjnego. Jeśli serwer zawiera błędy lub złośliwy kod, może odczytać pliki, do których ma dostęp Twój użytkownik.

2. Ochrona sekretów i kluczy API

Nigdy nie przechowuj produkcyjnych kluczy w repozytorium. Używaj globalnej konfiguracji ~/.claude/settings.json dla wrażliwych tokenów lub przekazuj zmienne środowiskowe przez pliki .env uwzględnione w .gitignore.

3. Audyt zewnętrznych pakietów przed podłączeniem

Zawsze audytuj repozytorium lub pakiet npm zewnętrznego serwera MCP przed dodaniem go do konfiguracji:

• Upewnij się, że kod źródłowy jest otwarty.
• Sprawdź liczbę pobrań i aktywność repozytorium.
• Zwracaj uwagę na zapytania sieciowe, które serwer wykonuje przy starcie.

4. Rozdzielenie poziomów konfiguracji

8. Praktyczny warsztat: krok po kroku

Wykonaj dwa praktyczne zadania, aby utrwalić materiał i zweryfikować poprawność podłączenia serwerów.

Zadanie 1. Podłączenie serwera MCP GitHub

1. Utwórz nowy Personal Access Token (classic lub fine-grained) na GitHubie w sekcji Settings → Developer settings z uprawnieniami repo oraz read:org.
2. Otwórz lub utwórz plik konfiguracyjny ~/.claude/settings.json:

3. Uruchom nową sesję Claude Code i wykonaj weryfikacyjny prompt:

Prompt do testów:
„Pokaż moje 5 ostatnio aktualizowanych repozytoriów na GitHubie i ich status.”

• Claude Code pomyślnie wywołał narzędzie GitHub bez błędów autentykacji.
• Otrzymano aktualną listę repozytoriów.

Zadanie 2. Podłączenie serwera Filesystem dla zewnętrznych notatek

Udostępnij Claude dostęp do zewnętrznego folderu z dokumentacją lub notatkami architektonicznymi:

1. Dodaj serwer filesystem do .claude/settings.json:

2. Zweryfikuj działanie zapytaniem do Claude:

Prompt do testów:
„Znajdź w folderze external-docs wszystkie pliki markdown opisujące architekturę API i stwórz ich krótki przegląd.”

• Claude odczytał pliki spoza roboczego katalogu projektu.
• Uogólnił znalezione informacje bez utraty kontekstu.

9. Szybka samoocena wiedzy

Sprawdź, jak dobrze przyswoiłeś fundamentalne zasady architektury Model Context Protocol.

Pytanie 1. Jaka jest podstawowa rola serwera MCP?

• A. Chmurowa maszyna wirtualna do hostingu modeli Claude
• B. Program adapter, który zapewnia modelowi językowemu standaryzowany dostęp do zewnętrznych narzędzi i danych
• C. Biblioteka do automatycznej kompresji wektorowych embeddingów
• D. Serwer webowy do publikacji skompilowanego kodu projektu

Pytanie 2. W którym pliku przechowywana jest konfiguracja serwerów przeznaczona tylko dla konkretnego repozytorium?

• A. ~/.claude/settings.json
• B. package.json
• C. .claude/settings.json w korzeniu projektu
• D. CLAUDE.md

Pytanie 3. Skąd Claude Code wie, którego narzędzia użyć do odpowiedzi na pytanie?

• A. Użytkownik musi jawnie wskazać flagę --tool=name przed każdym zapytaniem
• B. Trzeba wcześniej wywołać komendę /mcp select
• C. Model analizuje semantykę zapytania oraz opisy schem JSON narzędzi, wybierając trafne samodzielnie
• D. Wywoływane są wszystkie narzędzia jednocześnie, a zbędne wyniki są odrzucane

10. Podsumowania i checklist architektury

Model Context Protocol czyni Claude Code elastycznym środowiskiem agentowym. Zamiast ręcznie kopiować zawartość plików czy schemy baz danych do dialogu, ustawiasz stałe kanały komunikacji raz.

Checklist gotowości Twojego środowiska

• Poziomy konfiguracji: Usługi globalne (GitHub, Web Search) wyniesiono do ~/.claude/settings.json, a specyficzne dla projektu (DB, dokumentacja) do .claude/settings.json.
• Bezpieczeństwo: Tokeny i hasła nie są commitowane do publicznego repozytorium; bazy danych podłączono z minimalnymi wymaganymi uprawnieniami (Read-Only do analizy).
• Testowanie narzędzi: Działanie serwerów zweryfikowano celowymi zapytaniami po uruchomieniu sesji.
• Rozszerzalność: Dla specyficznych zadań wewnętrznych utworzono szablon własnego serwera w TypeScript przez @modelcontextprotocol/sdk.