Przez długi czas Claude był potężnym narzędziem zamkniętym w bańce własnego okna kontekstu. Wiedział dużo, ale nic nie mógł zrobić poza pisaniem tekstu. MCP zmienia tę dynamikę.

Czym jest Model Context Protocol?

MCP (Model Context Protocol) to otwarty standard komunikacyjny stworzony przez Anthropic pod koniec 2024 roku. Definiuje, jak modele językowe mogą rozmawiać z zewnętrznymi programami — serwerami narzędzi, bazami danych, API usług chmurowych. W praktyce MCP server to mały, oddzielny program. Serwer rejestruje zestaw narzędzi (tools) — funkcji, które Claude może wywołać podczas rozmowy. Kiedy poprosisz Claude o przeszukanie sieci, zrobienie screenshota lub wykonanie zapytania do bazy danych — to właśnie MCP server robi tę faktyczną robotę.

sequenceDiagram
    participant U as Użytkownik
    participant C as Claude
    participant M as MCP Server
    participant E as Zewnętrzny serwis

    U->>C: "Znajdź dokumentację Flask 3.x"
    C->>M: tool_call: search("Flask 3.x docs")
    M->>E: HTTP GET → Brave Search API
    E-->>M: Wyniki wyszukiwania
    M-->>C: Lista stron + fragmenty
    C-->>U: Synteza odpowiedzi z wynikami

Trzy prymitywy MCP

Każdy MCP server może exportować trzy typy obiektów:

Dwa tryby transportu

MCP wspiera dwa sposoby komunikacji między Claude a serwerem:

Jeśli instalujesz serwer przez npx lub uvx — to stdio. Jeśli wpisujesz URL w polu "custom connector" — to HTTP.

Ile serwerów MCP można podłączyć?

Nie ma twardego limitu wbudowanego w Claude. Ale jest inny limit, który szybko daje o sobie znać: tokeny.

Token overhead — ukryty koszt

Każdy podłączony MCP server wstrzykuje pełne definicje wszystkich swoich narzędzi do kontekstu każdej wiadomości, niezależnie od tego, czy w danej rozmowie ich używasz. każde wywołanie API Claude Opus kosztuje Cię per token. Nakładanie 10 serwerów to nie tylko problem z dostępną przestrzenią — to realny wzrost rachunków.

Tool Search — jak Claude Code rozwiązuje ten problem

Claude Code wprowadził mechanizm Tool Search, zamiast ładować wszystkie schematy narzędzi przy starcie sesji, do kontekstu wchodzą tylko nazwy narzędzi. Pełny schemat jest pobierany na żądanie, gdy Claude faktycznie potrzebuje danego narzędzia.

Tool Search jest domyślnie włączony w Claude Code. W Claude Desktop tej optymalizacji nie ma — tym bardziej warto tam trzymać liczbę serwerów pod kontrolą. Aktualne zużycie tokenów sprawdzisz komendą /context wewnątrz sesji Claude Code.

Konfiguracja

Masz dwa miejsca konfiguracji — zależnie od tego, czy pracujesz w Claude Desktop, czy Claude Code.

Claude Desktop

Plik konfiguracyjny:

%APPDATA%\Claude\claude_desktop_config.json

Przykładowa konfiguracja z dwoma serwerami:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "twój-klucz-api"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\TwójLogin\\Documents",
        "C:\\Users\\TwójLogin\\Projects"
      ]
    }
  }
}

Po edycji: zamknij Claude Desktop całkowicie (prawy klik na ikonę w tray → Quit) i uruchom ponownie.

Claude Code

Claude Code przechowuje konfigurację MCP w pliku .mcp.json w katalogu projektu (zakres lokalny) lub globalnie. Zarządzasz serwerami przez CLI:

# Dodaj serwer (interaktywnie)
claude mcp add brave-search -- npx -y @modelcontextprotocol/server-brave-search

# Dodaj serwer z kluczem API przez JSON
claude mcp add-json brave-search '{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-brave-search"],
  "env": {"BRAVE_API_KEY": "twój-klucz"}
}'

# Listuj aktywne serwery
claude mcp list

# Usuń serwer
claude mcp remove brave-search

Konfiguracja zapisana do .mcp.json w projekcie — dobra praktyka, żeby nie mieszać narzędzi do różnych projektów.

Diagnostyka — serwer MCP się nie ładuje

Konfig wygląda poprawnie, restartujesz Claude Code, a serwer nadal nie pojawia się w dostępnych narzędziach. Najczęstsza przyczyna: pakiet nie istnieje w npm registry pod podaną nazwą.

Sprawdź czy pakiet istnieje

Najpierw pretestuj czy pakiet w ogóle można uruchomić:

npx -y <nazwa-pakietu> --help

Jeśli zobaczysz błąd npm error 404 Not Found — nazwa pakietu jest zła. Przykład:

npm error 404 Not Found - GET https://registry.npmjs.org/@tavily%2fmcp-server
npm error 404  '@tavily/mcp-server@*' is not in this registry

W takim przypadku sprawdź aktualną nazwę pakietu w dokumentacji danego serwera lub na npmjs.com. Nazwy pakietów MCP potrafią się zmieniać między wersjami.

Jeśli pakiet startuje, ale serwer się nie ładuje

Gdy npx -y <pakiet> --help działa, ale serwer nie pojawia się w Claude Code po restarcie — sprawdź kolejno:

1. Klucz API — serwer może cicho failować jeśli klucz jest pusty lub nieprawidłowy. Zweryfikuj klucz w panelu dostawcy.
2. Składnia JSON — jeden przecinek za dużo lub za mało w .mcp.json i cały plik jest ignorowany. Sprawdź plik przez jsonlint.com.
3. Zakres pliku — .mcp.json w katalogu projektu działa tylko dla tego projektu. Dla konfiguracji globalnej użyj pliku w ~/.claude/mcp.json.
4. Logi startowe — uruchom Claude Code z flagą --debug i sprawdź czy przy starcie pojawia się błąd dla danego serwera.

Ostrzeżenie na Windows: npx wymaga cmd /c wrapper

Claude Code może wyświetlić ostrzeżenie przy ładowaniu serwerów:

[Warning] mcpServers.brave-search: Windows requires 'cmd /c' wrapper to execute npx

Oznacza to, że Claude Code nie może uruchomić npx bezpośrednio. Przyczyna: na Windows npx bez rozszerzenia to skrypt, a spawn() (Node.js) nie potrafi go uruchomić bez powłoki.

Rozwiązanie bez wrappera — zamień "command": "npx" na "command": "npx.cmd". To natywny plik wykonywalny npm, który spawn() uruchamia bezpośrednio:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "BSA..." }
    },
    "tavily": {
      "command": "npx.cmd",
      "args": ["-y", "tavily-mcp"],
      "env": { "TAVILY_API_KEY": "tvly-..." }
    }
  }
}

npx.cmd jest dostępne wszędzie tam, gdzie zainstalowany jest Node.js (C:\Program Files\nodejs\npx.cmd). Po zmianie przeładuj sesję — ostrzeżenia znikną.