MCP #1 — Czym jest?

Claude jako model językowy operuje wyłącznie w granicach własnego okna kontekstu: przetwarza tekst, ale bez możliwości działania na zewnętrznych systemach. Model Context Protocol (MCP) wprowadza warstwę integracji, która pozwala modelowi wywoływać narzędzia, odpytywać API i odczytywać dane z zewnętrznych źródeł.

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ą komunikować się 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), czyli funkcji, które Claude może wywołać podczas rozmowy. Przeszukanie sieci, zrobienie screenshota lub wykonanie zapytania do bazy danych odbywa się właśnie przez MCP server.

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 eksportować trzy typy obiektów:

Dwa tryby transportu

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

Serwery uruchamiane przez npx lub uvx korzystają z transportu stdio. Wpisanie URL w polu "custom connector" oznacza transport 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 są używane. Każde wywołanie API Claude jest rozliczane per token. Nakładanie 10 serwerów to nie tylko problem z dostępną przestrzenią kontekstu, ale też realny wzrost kosztów per zapytanie.

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 można sprawdzić komendą /context wewnątrz sesji Claude Code.

Konfiguracja

Konfiguracja MCP różni się w zależności od klienta: Claude Desktop i Claude Code używają osobnych mechanizmów.

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 katalogu projektu działa tylko w jego zakresie, co pozwala utrzymywać osobne zestawy narzędzi dla różnych projektów.

Diagnostyka — serwer MCP się nie ładuje

Gdy konfiguracja wygląda poprawnie, a serwer nadal nie pojawia się w dostępnych narzędziach po restarcie, najczęstszą przyczyną jest to, że pakiet nie istnieje w npm registry pod podaną nazwą.

Sprawdź czy pakiet istnieje

Najpierw sprawdź, 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

Jeśli npx -y <pakiet> --help działa, ale serwer nie pojawia się w Claude Code po restarcie, należy sprawdzić kolejno:

1. Klucz API — serwer może kończyć się błędem bez komunikatu, 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. Na Windows npx bez rozszerzenia to skrypt powłoki, a spawn() w Node.js nie potrafi go uruchomić bez pośrednictwa shella.

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ą.