Claude + serwery MCP - jak podłączyć agenta do swoich systemów

Seria Claude Code · JSystems

Wyobraź sobie, że Twój asystent AI nie tylko pisze kod - realnie działa w Twoim środowisku. Sprawdza status pull requesta i tłumaczy, co każda zmiana robi. Odpytuje bazę danych zwykłym zdaniem - sam pisze SQL i zwraca wynik. Otwiera przeglądarkę i testuje Twoją aplikację, klikając i wypełniając formularze. Sięga po najświeższą dokumentację biblioteki, zamiast podsuwać przestarzałe API. Czyta i porządkuje pliki projektu, wysyła podsumowanie na Slacka, zakłada ticket w systemie zadań. Wszystko z jednego terminala - bez otwierania przeglądarki, bez kopiowania odpowiedzi między oknami, bez ręcznego przepisywania danych między systemami.

To nie science fiction. Dokładnie to robi Claude dzięki serwerom MCP (Model Context Protocol) - otwartemu standardowi, który podłącza go do Twoich narzędzi i danych. W tym artykule przejdziemy całą drogę: od podłączenia gotowego serwera jedną komendą, przez Playwright (sterowanie przeglądarką) i Context7 (zawsze aktualna dokumentacja bibliotek), aż po zbudowanie własnego serwera MCP dla firmowego systemu - z bezpieczeństwem, zarządzaniem serwerami i debugowaniem włącznie. Od zera, krok po kroku.

Krok 1 - Zrozum czym jest protokół MCP

Protokół to zestaw reguł komunikacji - tak jak w życiu codziennym mamy protokół dyplomatyczny (kto komu podaje rękę, kto mówi pierwszy). W informatyce protokół określa: jak dwa programy rozmawiają ze sobą, w jakim formacie wysyłają dane i jak odpowiadają na błędy.

Problem przed MCP: Każde narzędzie AI musiało integrować się z każdym zewnętrznym systemem osobno, na swój własny sposób. Chaos. 10 narzędzi × 20 systemów = 200 różnych integracji.

Rozwiązanie MCP: Jeden standardowy protokół. Budujesz serwer MCP raz - działa z Claude, ale też z innymi narzędziami AI wspierającymi ten standard.

Krok 2 - Zrozum jak to działa (przepływ komunikacji)

Gdy piszesz do Claude "Sprawdź otwarte issue #234 na GitHubie", dzieje się tak:

1. Claude decyduje, że potrzebuje narzędzia GitHub
2. Claude wysyła żądanie do serwera MCP GitHub w ustandaryzowanym formacie JSON
3. Serwer MCP tłumaczy to żądanie na API GitHuba i pobiera dane
4. Dane wracają do Claude, który formułuje odpowiedź

Wolisz nauczyć się tego z doświadczonym trenerem w formie warsztatowej? Szkolenie MCP z terminem gwarantowanym -->

Co serwer MCP może udostępniać - nie tylko narzędzia

Większość serwerów daje Claude narzędzia (Tools) - funkcje, które wywołuje. Ale protokół MCP ma trzy rodzaje rzeczy i warto wiedzieć, że istnieją:

• Narzędzia (Tools) - akcje do wykonania: zapytanie do bazy, wywołanie API, otwarcie strony.
• Zasoby (Resources) - dane do odczytu, które serwer wystawia jako kontekst: pliki, rekordy, dokumenty.
• Szablony promptów (Prompts) - gotowe polecenia, które serwer podsuwa (np. jako komendy do wyboru).

W praktyce 90% wartości to narzędzia - ale budując własny serwer, pamiętaj, że możesz wystawić też zasoby i gotowe prompty.

Krok 3 - Podłącz swój pierwszy serwer MCP

Najprościej podłączyć gotowy serwer jedną komendą - Claude sam zapisze konfigurację. Zacznijmy od Filesystem, który da Claude dostęp do wskazanego katalogu z plikami:

claude mcp add pliki -- npx -y @modelcontextprotocol/server-filesystem /home/user/projekt

Na Windowsie owiń uruchomienie w cmd /c:

claude mcp add pliki -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\projekty\moj-projekt

Sprawdź połączenie komendą /mcp - zobaczysz serwer „pliki” i jego narzędzia. I to wszystko: od teraz pytasz naturalnym językiem (np. „przeczytaj README i streść architekturę projektu”), a Claude sięgnie do plików.

{
  "mcpServers": {
    "pliki": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projekt"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": { "CONTEXT7_API_KEY": "twoj_klucz_opcjonalny" }
    }
  }
}

Każdy klucz w mcpServers to dowolna nazwa serwera, command i args to polecenie, które go uruchamia, a env przekazuje sekrety (np. klucz API). Tej samej komendy claude mcp add użyjemy za chwilę dla kolejnych serwerów.

Zarządzanie podłączonymi serwerami

Gdy masz już kilka serwerów, przydają się komendy do panowania nad nimi:

• claude mcp list - lista wszystkich serwerów i ich status (połączony / błąd).
• claude mcp get nazwa - szczegóły jednego serwera: komenda, zakres, zmienne środowiskowe.
• claude mcp remove nazwa - odłącz serwer, którego już nie używasz.
• /mcp (w trakcie sesji) - szybki podgląd podłączonych serwerów i ich narzędzi.

Dzięki temu nie zgadujesz, co masz wpięte - w każdej chwili sprawdzisz stan i posprzątasz.

Zakresy - dla kogo widoczny jest serwer

Przy claude mcp add flagą --scope decydujesz, kto zobaczy dany serwer:

• local (domyślny) - tylko Ty i tylko w tym projekcie. Dobre na eksperymenty.
• project (--scope project) - zapis w pliku .mcp.json w repozytorium. Commitujesz go i cały zespół ma te same serwery z automatu.
• user (--scope user) - Ty, ale we wszystkich projektach (np. Context7, którego chcesz mieć wszędzie).

Reguła: wspólne dla zespołu --> project (do repo), Twoje osobiste --> user, eksperymenty --> local. Dokładnie ta sama logika co przy CLAUDE.md - wspólne wersjonujesz, prywatne trzymasz osobno.

Popularne gotowe MCP serwery - co potrafią

Anthropic i społeczność stworzyły setki, a nawet tysiące gotowych serwerów MCP. Nie musisz nic kodować - wystarczy skonfigurować:

GitHub MCP

Daje Claude dostęp do:

• Listowania i czytania plików z repozytoriów
• Przeglądania issues i pull requests
• Tworzenia issues i komentarzy
• Wyszukiwania kodu

Przykład: "Znajdź wszystkie otwarte PR gdzie jestem wymieniony jako reviewer i opisz co każdy zmienia"

Dlaczego to ważne dla programisty: Zamiast ręcznie przeglądać 20 otwartych PR, dostajesz podsumowanie w 10 sekund. Claude przeczyta kod, zrozumie kontekst i wyjaśni co każda zmiana robi - bez otwierania przeglądarki.

PostgreSQL / SQLite MCP

Claude może:

• Wykonywać zapytania SELECT (read-only dla bezpieczeństwa - Claude nie może przypadkowo usunąć danych)
• Przeglądać schemat bazy danych (jakie tabele, jakie kolumny)
• Analizować dane i generować raporty

Przykład: "Pokaż mi 10 produktów z najwyższym wzrostem sprzedaży w tym miesiącu" - Claude sam napisze SQL, wykona i zwróci wyniki.

Filesystem MCP

Bezpieczny dostęp do plików - możesz ograniczyć do konkretnych katalogów. Claude może czytać, tworzyć i modyfikować pliki w wyznaczonym obszarze.

Analogia: To jak klucz do konkretnego pokoju, nie do całego budynku. Ustawiasz, że Claude ma dostęp tylko do folderu /home/user/projects, ale nie do /etc ani do plików systemowych.

Playwright MCP

Daje Claude dostęp do przeglądarki - może nawigować po stronach, klikać elementy, wypełniać formularze, robić screenshoty. Używany m.in. do automatyzacji i scrapingu.

Przykład użycia: "Sprawdź czy wszystkie linki na stronie działają i zwróć listę tych z błędem 404". Claude otworzy przeglądarkę, przejdzie przez każdy link i sporządzi raport - automatycznie.

Playwright MCP w praktyce - Claude steruje przeglądarką

Playwright MCP daje Claude pełną kontrolę nad przeglądarką: wchodzi na strony, klika, wypełnia formularze, czyta zawartość i robi zrzuty. Dla programisty to znaczy, że Claude przetestuje Twoją aplikację webową, wypełni powtarzalny panel albo wyciągnie dane ze strony - bez pisania skryptów.

Podłączasz jedną komendą (przeglądarka pobierze się przy pierwszym uruchomieniu):

claude mcp add przegladarka -- npx @playwright/mcp@latest

Potem wydajesz polecenie zwykłym językiem, a Claude sam tłumaczy je na akcje w przeglądarce:

A oto strona, którą Claude otworzył i na której może dalej działać - klikać, wypełniać, testować:

Przykład: Claude wypełnia formularz

Jedno zdanie po polsku - i Claude wykonuje całyą sekwencję: otwiera stronę, odczytuje strukturę formularza (browser_snapshot), wypełnia pola jedno po drugim i robi screenshot do weryfikacji.

To samo działa dla panelu admina, strony logowania, checkoutu e-commerce czy dowolnego innego UI — Claude czyta DOM, nie szuka po współrzędnych ekranu.

Szczególnie ciekawy przypadek to panele zarządzania infrastrukturą: Proxmox, AWS EC2, Azure VM, DigitalOcean — wszystkie mają interfejs webowy. Możesz dosłownie powiedzieć Claude:

> Wejdź na panel Proxmox pod 192.168.1.2:8006, utwórz LXC Debian 12
> z 2 vCPU, 2 GB RAM i 20 GB dysku, VMID 210, hostname web-staging

Claude zaloguje się (użyjesz swojego hasła), przejdzie przez kreator „Create CT”, wypełni wszystkie pola i poczeka na Twoje „tak” zanim kliknie Finish. To samo w AWS Console: Launch instance — t3.medium, Ubuntu 24.04, SSD 30 GB, security group web-sg — Claude klika kolejne kroki kreatora i zatrzymuje się przed finalnym potwierdzeniem. Zamiast 15 kliknięć w panelu masz jedno zdanie.

Bonus: podłącz Context7 - koniec z nieaktualnymi przykładami kodu

Jeśli masz dopisać tylko jeden serwer MCP, niech to będzie Context7. Rozwiązuje problem, który zna każdy, kto kazał AI napisać kod: model uczył się na dokumentacji sprzed miesięcy, więc podsuwa przestarzałe API - metody, których już nie ma, składnię z poprzedniej wersji biblioteki. Tracisz potem czas na debugowanie zmyślonego kodu.

Context7 wciąga do kontekstu Claude aktualną, wersjonowaną dokumentację dowolnej biblioteki - na żądanie. Dopisujesz w prompcie use context7, a Claude czyta prawdziwe, świeże docs (React, Next.js, Prisma, FastAPI, Tailwind… setki bibliotek) i pisze kod zgodny z TĄ wersją, której naprawdę używasz.

Dlaczego to bomba i każdy programista powinien mieć to wpięte:

• Zero halucynacji API - kod zgodny z aktualnym wydaniem biblioteki, nie sprzed roku.
• Konkretna wersja - dostajesz dokumentację dla Next.js 15, a nie 13.
• Bez przeklejania z docsów - Claude sam wciąga dokładnie to, co potrzebne do zadania.
• Setki bibliotek i frameworków - jeden serwer pokrywa praktycznie cały stack.

Podłącz (jedna komenda, globalnie dla Twojego konta):

claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp

Wolisz wersję zdalną (bez Node) albo wyższe limity z kluczem? Klucz jest opcjonalny - pobierzesz go z context7.com/dashboard:

claude mcp add --scope user --transport http --header "CONTEXT7_API_KEY: TWOJ_KLUCZ" context7 https://mcp.context7.com/mcp

Użycie - wystarczy dopisać use context7 do polecenia:

> Napisz middleware w Next.js sprawdzający JWT w cookies i przekierowujący
  niezalogowanych użytkowników na /login. use context7

Krok 4 - Zbuduj własny serwer MCP w TypeScript

Gdy gotowe serwery nie wystarczają, budujesz własny - to zwykła aplikacja Node.js, którą Claude uruchamia w tle. Poniżej kompletny, działający przykład: serwer dla firmowego ERP, który da Claude dwa narzędzia - sprawdzenie statusu faktury i listę przeterminowanych płatności. Przejdziemy całą drogę: od pustego katalogu do działającego narzędzia w Claude Code.

1. Załóż projekt i zainstaluj zależności

W terminalu, w pustym katalogu:

mkdir mcp-erp && cd mcp-erp
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

2. Dwa pliki konfiguracji

W package.json dopisz "type": "module" i skrypt budowania:

{
  "name": "mcp-erp",
  "version": "1.0.0",
  "type": "module",
  "scripts": { "build": "tsc" }
}

Obok stwórz tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

3. Serce serwera - plik src/index.ts

Każde server.tool(...) to jedno narzędzie, które zobaczy Claude: nazwa, opis (po nim Claude pozna, kiedy go użyć), parametry (walidowane przez Zod) i funkcja z Twoją logiką. W środku wpisujesz zapytanie do bazy albo wywołanie API ERP - tu dla jasności są dane przykładowe:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "firmowy-erp", version: "1.0.0" });

// NARZEDZIE 1: status faktury po numerze
server.tool(
  "status_faktury",
  "Zwraca status płatności faktury po jej numerze",
  { numer: z.string().describe("numer faktury, np. FV/2026/001") },
  async ({ numer }) => {
    // TODO: tu podłącz swoją bazę / API ERP. Poniżej dane przykładowe:
    const status = numer.endsWith("1") ? "opłacona" : "oczekuje na płatność";
    return { content: [{ type: "text", text: `Faktura ${numer}: ${status}` }] };
  }
);

// NARZEDZIE 2: przeterminowane faktury
server.tool(
  "przeterminowane_faktury",
  "Zwraca listę faktur po terminie płatności",
  { min_dni: z.number().optional().describe("minimalna liczba dni po terminie") },
  async ({ min_dni = 0 }) => {
    const dane = [
      { numer: "FV/2026/014", dni: 12, kwota: "4 200 zł" },
      { numer: "FV/2026/019", dni: 31, kwota: "980 zł" },
    ].filter((f) => f.dni >= min_dni);
    const txt = dane.map((f) => `${f.numer} - ${f.dni} dni, ${f.kwota}`).join("\n");
    return { content: [{ type: "text", text: txt || "Brak przeterminowanych faktur." }] };
  }
);

// Uruchamiamy serwer na stdio - Claude rozmawia z nim przez wejście/wyjście
await server.connect(new StdioServerTransport());

4. Zbuduj projekt

npm run build      # kompiluje src/index.ts do dist/index.js

5. Podłącz do Claude Code i przetestuj

Jedna komenda rejestruje serwer (podaj pełną ścieżkę do zbudowanego pliku):

claude mcp add erp -- node /pelna/sciezka/mcp-erp/dist/index.js

Sprawdź, że się podłączył - w sesji Claude Code wpisz /mcp, powinieneś zobaczyć serwer „erp” i jego dwa narzędzia. Teraz po prostu zapytaj naturalnym językiem:

> Jaki jest status faktury FV/2026/001?
> Pokaż faktury przeterminowane o ponad 20 dni

Claude sam rozpozna, że ma użyć Twojego narzędzia, wywoła odpowiednią funkcję i poda wynik. Od teraz każdą firmową operację (magazyn, CRM, wysyłka etykiet) dodajesz jako kolejne server.tool(...) - a Claude dostaje dostęp do Twoich systemów bez wychodzenia z terminala.

Bezpieczeństwo MCP - co kontrolować

• Read-only by default - serwery baz danych powinny mieć uprawnienia tylko do SELECT. Utwórz osobnego użytkownika bazy z ograniczonymi prawami - jeśli Claude zostanie skompromitowany, nie będzie mógł usunąć danych
• Approval flow - Claude Code może pytać użytkownika o potwierdzenie przed wrażliwymi operacjami (wysłanie emaila, zapis do bazy)
• Scope ograniczony - filesystem MCP tylko do wskazanych katalogów, nie do / (katalogu głównego systemu)
• Audit log - loguj każde wywołanie narzędzia MCP do pliku lub systemu monitoringu. Będziesz wiedział kto co robił i kiedy
• Secrets w env - nigdy nie hardkoduj tokenów w CLAUDE.md ani w kodzie - używaj zmiennych środowiskowych (sekcja "env" w konfiguracji)

Częste błędy przy konfiguracji MCP

• Błąd 1: Token z za szerokimi uprawnieniami
  Tworzysz jeden token GitHub z uprawnieniami do wszystkiego. Lepiej: stwórz token tylko z uprawnieniami read (read:repo, read:issues) - jeśli token wycieknie, atakujący nie może nic zapisać.
• Błąd 2: Serwer MCP z dostępem do całego systemu plików
  Ustawienie / zamiast konkretnego katalogu daje Claude dostęp do WSZYSTKICH plików na dysku - w tym kluczy SSH, pliku hosts, konfiguracji systemu. Zawsze podawaj konkretny katalog projektu.
• Błąd 3: Brak obsługi błędów w własnym serwerze MCP
  Jeśli serwer MCP crashuje bez odpowiedniego komunikatu, Claude dostaje tajemniczy błąd i nie wie co poszło nie tak. Zawsze owijaj wywołania zewnętrznych systemów w try/catch i zwracaj czytelny komunikat błędu.

Gdy serwer nie wstaje - MCP Inspector

Serwer się nie łączy albo narzędzie nie odpowiada? Zamiast zgadywać, odpal MCP Inspector - wizualny debugger, który uruchamia serwer i pozwala ręcznie wywołać każde narzędzie:

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /home/user/projekt

Otworzy się panel w przeglądarce: widzisz listę narzędzi, klikasz, wpisujesz parametry i sprawdzasz odpowiedź. Najszybszy sposób, żeby ustalić, czy problem jest w serwerze, czy w konfiguracji.

Przykład workflow z wieloma MCP naraz

Wpisujesz do Claude Code: "Sprawdź otwarte issue #234 na GitHubie, znajdź powiązane pliki w kodzie i napisz fix z testem"

1. Claude wywołuje GitHub MCP --> pobiera treść issue #234 (wie czego szukać)
2. Claude czyta powiązane pliki przez filesystem MCP (rozumie istniejący kod)
3. Claude pisze fix bezpośrednio w plikach (modyfikuje kod)
4. Claude uruchamia testy przez terminal (sprawdza czy fix działa)
5. Claude tworzy PR przez GitHub MCP (publikuje zmiany)

Całość bez opuszczania terminalu, bez kopiowania kodu do chatbota, bez manualnego "popraw tu i tam".