Czym jest MCP i jak skonfigurować go w Claude Code

Kilka miesięcy temu zacząłem zauważać, że Claude Code potrafi przeszukiwać internet, pytać Jirę i uruchamiać zadania w tle, a ja nie muszę przy tym zmieniać kontekstu. Nie dlatego, że ma te możliwości wbudowane, ale dzięki protokołowi o nazwie MCP. Ten wpis wyjaśnia, czym MCP faktycznie jest, jak działa architektura i jak podłączyć to do Claude Code. Następnym razem pokażę swój własny setup: które serwery używam, jak przechowuję dane uwierzytelniające i czego nauczyłem się po codziennym używaniu tego przez kilka miesięcy.

Czym jest MCP

MCP to skrót od Model Context Protocol. Jest to otwarty standard, opublikowany przez Anthropic, który definiuje, jak asystent AI może komunikować się z zewnętrznymi usługami. Można to traktować jako wspólny język dla integracji narzędzi.

Przed MCP każda integracja była napisana od zera. Asystent potrzebował własnego kodu do rozmowy z GitHubem, innego do zapytania bazy danych, jeszcze innego do listowania plików. MCP zastępuje to jednym protokołem, który obie strony implementują. Strona AI staje się klientem. Strona narzędziowa staje się serwerem. Mówią tym samym językiem.

Analogia, która u mnie działa: MCP ma się do asystentów AI tak, jak LSP (Language Server Protocol) ma się do edytorów kodu. LSP pozwolił każdemu edytorowi mieć podświetlanie składni i autouzupełnianie dla każdego języka dzięki uzgodnieniu jednego protokołu. MCP robi to samo dla dostępu AI do narzędzi.

Architektura

Claude Code działa jako klient MCP. Gdy konfigurujesz serwer MCP, Claude Code łączy się z nim przy starcie i pyta: “Co potrafisz zrobić?” Serwer odpowiada listą swoich możliwości. Od tego momentu, gdy jakieś zadanie wymaga czegoś, co serwer oferuje, Claude Code może to wywołać.


graph LR
    A["Claude Code
MCP Client"] -->|"initialize
list tools"| B["MCP Server"]
    B -->|"tool list
capabilities"| A
    A -->|"tool call
{ name, args }"| B
    B -->|"tool result
{ content }"| A

Połączenie odbywa się przez jeden z dwóch transportów:

Stdio łączy Claude Code z lokalnie uruchomionym procesem przez standardowe wejście/wyjście. Uruchamiasz proces serwera, Claude Code go forkuje i komunikuje się przez pipe. Dobre dla lokalnych narzędzi, proste w debugowaniu.

HTTP łączy z zdalnym serwerem przez HTTPS. Claude Code wysyła żądania, serwer odpowiada. Dobre dla hostowanych usług i wszystkiego, co musi działać ciągle.

Jest też SSE (Server-Sent Events), ale jest przestarzałe i nie warto go używać dla nowych serwerów.

Każdy serwer MCP ma swój cykl życia:

Klient łączy się i wysyła initialize z wersją protokołu i informacjami o kliencie
Serwer odpowiada swoimi informacjami i możliwościami
Klient wysyła initialized dla potwierdzenia
Normalna praca: klient wywołuje narzędzia, serwer wykonuje i zwraca wyniki


sequenceDiagram
    participant C as Claude Code
    participant S as MCP Server

    C->>S: initialize (protocol version, client info)
    S-->>C: server info + capabilities
    C->>S: initialized
    Note over C,S: Connection ready

    C->>S: tools/list
    S-->>C: [{ name, description, inputSchema }, ...]

    C->>S: tools/call { name: "read_file", arguments: { path: "/tmp/data.txt" } }
    S-->>C: { content: [{ type: "text", text: "..." }] }

Trzy podstawowe elementy

Serwery MCP udostępniają trzy typy rzeczy: Tools, Resources i Prompts.

Tools to wywoływalne funkcje. Serwer definiuje je z nazwą, opisem i schematem JSON dla danych wejściowych. Klient wywołuje je z argumentami i dostaje wynik. Większość tego, czego faktycznie używasz na co dzień, to narzędzia: wyszukiwanie w internecie, zapytania do bazy danych, listowanie plików, wysyłanie wiadomości.

Resources to dane, które serwer udostępnia do odczytu. Zasób ma URI (np. file:///home/user/config.json lub db://mydb/users) i opcjonalne metadane. Klient może listować dostępne zasoby i czytać ich zawartość. Resources sprawdzają się, gdy chcesz dać asystentowi dostęp do odczytu czegoś bez robienia z tego pełnego wywołania narzędzia.

Prompts to szablony promptów wielokrotnego użytku, które serwer definiuje. Klient może je listować i wywoływać z argumentami, dostając z powrotem ustrukturyzowaną wiadomość. Rzadziej używane, ale przydatne, gdy chcesz, żeby serwer definiował, jak powinno wyglądać podejście do określonych zadań.


graph TD
    S["MCP Server"] --> T["Tools
callable functions"]
    S --> R["Resources
readable data"]
    S --> P["Prompts
reusable templates"]
    T --> T1["read_file(path)"]
    T --> T2["search(query)"]
    T --> T3["create_issue(title, body)"]
    R --> R1["file:///project/README.md"]
    R --> R2["db://mydb/schema"]
    P --> P1["code-review(diff)"]

W praktyce większość serwerów MCP od firm trzecich to prawie wyłącznie narzędzia. Resources i Prompts są w specyfikacji, jeśli budujesz własny serwer, ale ekosystem domyślnie opiera się na narzędziach niemal do wszystkiego.

Konfiguracja MCP w Claude Code

Są dwa sposoby dodawania serwerów MCP do Claude Code: CLI i plik konfiguracyjny.

Przez CLI

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Dodaj serwer stdio
claude mcp add --transport stdio filesystem -- npx @modelcontextprotocol/server-filesystem /home/user/projects

# Dodaj serwer HTTP
claude mcp add --transport http tavily https://mcp.tavily.com/mcp

# Wylistuj skonfigurowane serwery
claude mcp list

# Usuń serwer
claude mcp remove filesystem

CLI przechowuje konfigurację w ~/.claude.json (poziom użytkownika, działa dla wszystkich projektów) lub w .claude/settings.json (poziom projektu).

Przez .mcp.json

Do konfiguracji na poziomie projektu wolę plik .mcp.json w katalogu głównym projektu. Jest czytelniejszy, można go wersjonować (z sekretami wykluczonymi przez .gitignore) i łatwo udostępnić strukturę bez danych uwierzytelniających.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/home/user/projects"
      ]
    }
  }
}

To minimum dla serwera stdio. Dla serwerów HTTP:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "mcpServers": {
    "tavily": {
      "type": "http",
      "url": "https://mcp.tavily.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TAVILY_API_KEY}"
      }
    }
  }
}

I bardziej kompletny przykład z kilkoma serwerami używającymi obu transportów:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/home/user/projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "tavily": {
      "type": "http",
      "url": "https://mcp.tavily.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TAVILY_API_KEY}"
      }
    }
  }
}

Gdy Claude Code startuje w tym katalogu projektu, czyta .mcp.json, łączy się ze wszystkimi skonfigurowanymi serwerami i narzędzia, które udostępniają, stają się dostępne w sesji.

Działający przykład: serwer filesystem

Serwer filesystem MCP to dobry pierwszy do wypróbowania. Zainstaluj i uruchom:

1
2
3
4
5
# Jednorazowe uruchomienie (npx pobiera i wykonuje)
npx @modelcontextprotocol/server-filesystem /home/user/projects

# Albo zainstaluj globalnie
npm install -g @modelcontextprotocol/server-filesystem

Dodaj do .mcp.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/home/user/projects"
      ]
    }
  }
}

Uruchom sesję Claude Code. Możesz teraz prosić go o listowanie plików, czytanie zawartości plików lub wyszukiwanie w skonfigurowanym katalogu. Narzędzia, które udostępnia, to między innymi read_file, write_file, list_directory, search_files i kilka innych.

Jak to wygląda w praktyce: Claude Code łączy się, pobiera listę narzędzi i za każdym razem, gdy zadanie wymaga odczytu pliku z tej ścieżki, wywołuje read_file przez serwer MCP zamiast potrzebować dostępu do powłoki. W sandboxowanym środowisku to istotna różnica.

Bezpieczeństwo

MCP daje asystentowi realny dostęp do realnych systemów. O to chodzi, ale to oznacza, że model zagrożeń ma znaczenie.

Kilka rzeczy, na które zwracam uwagę.

Ogranicz scope uprawnień. Nie dawaj serwerowi MCP tokena GitHub z dostępem do zapisu we wszystkich repozytoriach, jeśli potrzebuje tylko odczytu jednego. Twórz tokeny z minimalnym zakresem uprawnień.

Wiedz, co udostępniasz. Serwer filesystem może czytać i pisać pliki w katalogu, który podasz. Jeśli wskażesz go na /, dajesz asystentowi dostęp do całego systemu plików. Wskazuj tylko na konkretny katalog, który jest potrzebny.

Uważaj na prompt injection. Serwery MCP zwracają dane, które trafiają do kontekstu asystenta. Jeśli atakujący może kontrolować, co serwer zwraca (złośliwy plik, spreparowany wynik wyszukiwania), może próbować wstrzyknąć instrukcje w te dane. Mój plik reguł dla tego przypadku traktuje wszystkie wyjścia narzędzi jako dane, nigdy jako instrukcje. System hooków dodaje kolejną warstwę: hook uprawnień, który automatycznie odrzuca destrukcyjne komendy niezależnie od tego, co mówi wyjście narzędzia.

Nigdy nie hardcoduj sekretów w .mcp.json. Używaj podstawiania zmiennych środowiskowych (${VAR_NAME}) i trzymaj sekrety w menedżerze sekretów lub pliku .env objętym .gitignore. Ja trzymam wszystkie w Vault i generuję plik konfiguracyjny przy starcie.

Uruchamiaj serwery MCP ze źródeł, którym ufasz. Złośliwy serwer może udostępniać narzędzia, które wyglądają przydatnie, ale eksfiltrują dane albo wykonują dowolne polecenia. Trzymaj się oficjalnych pakietów i dobrze znanych projektów społeczności.

Sam protokół nie definiuje autoryzacji poza uwierzytelnianiem na poziomie transportu. Kontrola dostępu leży całkowicie po twojej stronie i po stronie serwera, który uruchamiasz.

Co jest dostępne

Oficjalne repozytorium MCP ma referencyjne serwery dla popularnych integracji: filesystem, GitHub, Postgres, SQLite, Slack, Google Drive i kilkanaście innych. Serwery społeczności pokrywają o wiele więcej przypadków.

Kilka przydatnych punktów startowych:

1
2
3
4
5
@modelcontextprotocol/server-filesystem    # Operacje na plikach
@modelcontextprotocol/server-github        # GitHub API
@modelcontextprotocol/server-postgres      # Zapytania PostgreSQL
@modelcontextprotocol/server-sqlite        # Zapytania SQLite
@modelcontextprotocol/server-slack         # Wiadomości Slack

Pojawiają się też hostowane serwery MCP. Tavily, Atlassian i inni publikują endpointy HTTP, na które możesz wskazać Claude Code bez uruchamiania czegokolwiek lokalnie. Potrzebujesz tylko klucza API i URL-a.

Co dalej

To tyle, jeśli chodzi o sam protokół. Następnym razem pokażę setup, z którego korzystam na co dzień: siedem serwerów MCP przez oba transporty, jak zarządzam danymi uwierzytelniającymi przez Vault tak, żeby nigdy nie pojawiały się w plikach konfiguracyjnych, których narzędzi używam najczęściej i kilka rzeczy, które zrobiłbym inaczej, gdybym zaczynał od zera. Jest to o wiele bardziej konkretne niż “wpisz tu swój token GitHub”.

Krótka wersja: gdy masz kilka dobrych serwerów podłączonych, przestajesz przełączać się między narzędziami. Asystent ogarnia wyszukiwanie, ja podejmuję decyzje. W połączeniu ze skillami i agentami, które wiedzą jak używać tych narzędzi, ten podział pracy jest wart czasu poświęconego na konfigurację.

Czym jest MCP#

Architektura#

Trzy podstawowe elementy#

Konfiguracja MCP w Claude Code#

Przez CLI#

Przez .mcp.json#

Działający przykład: serwer filesystem#

Bezpieczeństwo#

Co jest dostępne#

Co dalej#