# Serwery MCP i Claude Code: praktyczny przewodnik po integracji i tworzeniu > Jak rozszerzyć możliwości Claude Code za pomocą Model Context Protocol: integracja z systemem plików, GitHub, PostgreSQL, Brave Search oraz tworzenie własnego serwera w TypeScript. 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. ```text ┌─────────────────────────────────────────────────────────────┐ │ Claude Code (Klient) │ └──────────────────────────────┬──────────────────────────────┘ │ JSON-RPC 2.0 (stdio / SSE) ▼ ┌─────────────────────────────────────────────────────────────┐ │ Serwer MCP (Adapter) │ └──────┬───────────────────────┼───────────────────────┬──────┘ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ System │ │ GitHub API │ │ Baza danych │ │ plików │ │ i Issues │ │ PostgreSQL │ └─────────────┘ └─────────────┘ └─────────────┘ ``` 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 | Scenariusz pracy | Bez MCP (bazowy Claude Code) | Z podłączonymi serwerami MCP | | :--- | :--- | :--- | | **Praca z plikami** | Tylko wewnątrz bieżącego katalogu projektu | Dostęp do dowolnych zatwierdzonych katalogów i notatek | | **Dane repozytorium** | Lokalne pliki przez `git diff` / `git log` | Odczyt issues, PR, code review oraz API GitHub | | **Bazy danych** | Tylko jeśli zainstalowano lokalny klient CLI | Bezpośredni odczyt schemy, tabel i wykonanie SQL | | **Wyszukiwanie informacji** | Lokalny grep / ripgrep w plikach | Aktualne wyszukiwanie w sieci w czasie rzeczywistym przez Brave/Tavily | | **Usługi wewnętrzne** | Niedostępne bez pisania skomplikowanych skryptów bash | Wywoływanie funkcji wewnętrznych API przez typowany SDK | --- ## 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ź. > [!NOTE] > Interakcja jest przejrzysta dla developera: nie musisz pamiętać nazw funkcji ani składni API. Claude samodzielnie wybiera najbardziej odpowiednie narzędzie na podstawie kontekstu zadania. --- ## 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. :::tabs === Projekt (.claude/settings.json) ```json { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "./docs" ] } } } ``` === Globalnie (~/.claude/settings.json) ```json { "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_your_token_here" } } } } ``` ::: ### Struktura parametrów konfiguracyjnych Każdy wpis serwera w sekcji `mcpServers` składa się z trzech kluczowych pól: | Parametr | Typ | Obowiązkowy | Opis i przeznaczenie | Przykłady wartości | | :--- | :--- | :--- | :--- | :--- | | `command` | `string` | Tak | Komenda uruchamiająca proces serwera | `"npx"`, `"node"`, `"uvx"`, `"docker"` | | `args` | `string[]` | Tak | Tablica argumentów uruchomienia (nazwa pakietu, ścieżki, parametry) | `["-y", "@anthropic-ai/mcp-filesystem", "/path"]` | | `env` | `object` | Nie | Słownik zmiennych środowiskowych do autoryzacji i kluczy API | `{"GITHUB_TOKEN": "ghp_...", "DEBUG": "1"}` | > [!TIP] > Jeśli używasz narzędzi w Pythonie, zamiast `npx` możesz wykorzystać `uvx` (z menedżera pakietów `uv`), np.: `"command": "uvx", "args": ["mcp-server-git"]`. --- ## 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. | Serwer | Oficjalny pakiet | Dostęp / Autentyfikacja | Główne możliwości | | :--- | :--- | :--- | :--- | | **Filesystem** | `@anthropic-ai/mcp-filesystem` | Ścieżki do zatwierdzonych folderów lokalnych | Odczyt, zapis i wyszukiwanie w katalogach zewnętrznych | | **GitHub** | `@anthropic-ai/mcp-github` | Personal Access Token (`GITHUB_TOKEN`) | Wyszukiwanie w repozytoriach, analiza issues, tworzenie PR | | **PostgreSQL** | `@anthropic-ai/mcp-postgres` | String połączenia (`connectionString`) | Inspekcja schem, odczyt tabel, wykonywanie zapytań SQL | | **Brave Search** | `@anthropic-ai/mcp-brave-search` | Klucz API wyszukiwania (`BRAVE_API_KEY`) | Dostęp do aktualnych informacji z internetu bez halucynacji | ### 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). ```json { "mcpServers": { "docs": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "/Users/username/Developer/knowledge-base" ] } } } ``` ### 2. Serwer GitHub Pozwala asystentowi bezpośrednio pracować z repozytoriami organizacji: czytać issues, zostawiać komentarze do PR i sprawdzać status pipeline’ów. ```json { "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } } } ``` ### 3. Serwer PostgreSQL Daje możliwość wykonywania przez Claude zapytań analitycznych lub diagnostycznych bezpośrednio do Twojej lokalnej lub zdalnej bazy danych. ```json { "mcpServers": { "postgres": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-postgres", "postgresql://postgres:password@localhost:5432/my_app_db" ] } } } ``` ### 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. ```json { "mcpServers": { "brave-search": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-brave-search" ], "env": { "BRAVE_API_KEY": "BSAu_your_brave_search_api_key" } } } } ``` --- ## 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. ```markdown Znaleziono 3 otwarte zadania przypisane do Ciebie: 1. **#42 — Fix login redirect loop** (Priorytet: Wysoki, Utworzono: 2 dni temu) 2. **#38 — Add rate limiting to auth API** (Priorytet: Średni, Utworzono: 5 dni temu) 3. **#35 — Update user profile settings page** (Priorytet: Niski, Utworzono: 1 tydzień temu) Czy chcesz szczegółowo przeanalizować kod w celu naprawy błędu w zadaniu #42? ``` --- ## 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: ```bash mkdir my-mcp-server && cd my-mcp-server npm init -y npm install @modelcontextprotocol/sdk zod npm install -D typescript @types/node tsx ``` ### Krok 2. Implementacja serwera (`server.ts`) Stwórz plik `server.ts` z definicją serwera i niestandardowego narzędzia: ```typescript import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; // 1. Ініціалізуємо сервер з метаданими const server = new McpServer({ name: "internal-crm-server", version: "1.0.0", }); // 2. Реєструємо інструмент пошуку користувача server.tool( "lookup-user", "Отримати профіль клієнта за його адресою електронної пошти", { email: z.string().email().describe("Email адреса зареєстрованого користувача"), }, async ({ email }) => { // Тут може бути реальний запит до CRM, Redis чи внутрішнього API const mockUser = { id: "usr_99812", email, name: "Олександр Коваленко", plan: "Enterprise", status: "active", createdAt: "2024-03-15T10:00:00Z", }; return { content: [ { type: "text", text: JSON.stringify(mockUser, null, 2), }, ], }; } ); // 3. Запускаємо сервер через стандартний stdio транспорт async function run() { const transport = new StdioServerTransport(); await server.connect(transport); console.error("Internal CRM MCP server started on stdio"); } run().catch((error) => { console.error("Server startup error:", error); process.exit(1); }); ``` ### Krok 3. Podłączenie serwera do Claude Code Dodaj utworzony serwer do `.claude/settings.json` swojego projektu: ```json { "mcpServers": { "crm": { "command": "npx", "args": [ "tsx", "/Users/username/Developer/my-mcp-server/server.ts" ] } } } ``` > [!TIP] > Użycie utility `tsx` pozwala uruchamiać pliki TypeScript bezpośrednio, bez konieczności wcześniejszego kompilowania przez `tsc`. --- ## 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 ```text ┌─────────────────────────────────────────────────────────────┐ │ ~/.claude/settings.json │ │ Narzędzia globalne: GitHub, Wyszukiwarka internetowa, Przeglądarka │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ .claude/settings.json │ │ Narzędzia lokalne: Dev PostgreSQL, specyficzne skrypty │ └─────────────────────────────────────────────────────────────┘ ``` > [!WARNING] > Unikaj podłączania serwerów z prawami zapisu do baz danych produkcyjnych (Production DB) w trybie deweloperskim. Do testów używaj oddzielnych replik Read-Only lub lokalnych kontenerów Docker. --- ## 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`: ```json { "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_ваш_токен_тут" } } } } ``` 3. Uruchom nową sesję Claude Code i wykonaj weryfikacyjny prompt: ```bash claude ``` > **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`: ```json { "mcpServers": { "external-docs": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "/шлях/до/вашої/папки/з_документами" ] } } } ``` 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 > [!TIP] > **Poprawna odpowiedź: B.** > Serwer MCP to lokalny lub zdalny proces działający jako most między modelem a usługami zewnętrznymi, udostępniający modelowi standaryzowane Tools, Resources oraz Prompts. --- ### 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` > [!TIP] > **Poprawna odpowiedź: C.** > Dla konfiguracji na poziomie pojedynczego projektu służy `.claude/settings.json`. Plik w katalogu domowym `~/.claude/settings.json` odpowiada za globalne narzędzia developera. --- ### 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 > [!TIP] > **Poprawna odpowiedź: C.** > Dzięki standaryzowanym opisom i schemom parametrów Claude ocenia intencję użytkownika i autonomicznie wywołuje potrzebne narzędzie, przekazując walidowane argumenty. --- ## 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 - [x] **Poziomy konfiguracji:** Usługi globalne (GitHub, Web Search) wyniesiono do `~/.claude/settings.json`, a specyficzne dla projektu (DB, dokumentacja) do `.claude/settings.json`. - [x] **Bezpieczeństwo:** Tokeny i hasła nie są commitowane do publicznego repozytorium; bazy danych podłączono z minimalnymi wymaganymi uprawnieniami (Read-Only do analizy). - [x] **Testowanie narzędzi:** Działanie serwerów zweryfikowano celowymi zapytaniami po uruchomieniu sesji. - [x] **Rozszerzalność:** Dla specyficznych zadań wewnętrznych utworzono szablon własnego serwera w TypeScript przez `@modelcontextprotocol/sdk`.