Agent bez narzędzi to chatbot. W pierwszym poście serii zdefiniowaliśmy narzędzia jako jeden z czterech filarów agenta. Teraz wejdziemy w szczegóły: jak agent sięga po narzędzia przez MCP, jaki protokół za tym stoi i jak zarządzać tym, żeby 50 narzędzi nie zjadło całego okna kontekstowego.

Trzy warstwy rozszerzeń w Claude Code

Claude Code ma trzy warstwy rozszerzeń, każda z innym mechanizmem:

graph TD
    CC[Claude Code]

    subgraph "Warstwa 3: Skills i Hooks"
        S1["/review, /deploy-check"]
        S2["PreToolCall, PostToolCall"]
    end

    subgraph "Warstwa 2: Serwery MCP"
        M1[GitHub MCP]
        M2[Context7]
        M3["Własne serwery"]
    end

    subgraph "Warstwa 1: Narzędzia wbudowane"
        R["Read / Edit / Write"]
        B["Bash / Grep / Glob"]
        A["Agent / TodoWrite"]
    end

    CC --> R
    CC --> M1
    CC --> S1
    R ~~~ M1
    M1 ~~~ S1

Warstwa 1: Narzędzia wbudowane

Wbudowane bezpośrednio w Claude Code. Zawsze dostępne, bez konfiguracji. Zoptymalizowane pod kątem tokenów — ich opisy są częścią systemu Claude Code i nie obciążają kontekstu w taki sam sposób jak MCP.

Przykłady: Read, Edit, Write, Bash, Grep, Glob, Agent, TodoWrite.

Warstwa 2: MCP (Model Context Protocol)

Zewnętrzne serwery dostarczające narzędzia przez standardowy protokół. Każdy serwer MCP to osobny proces (stdio) lub endpoint HTTP, który rejestruje swoje narzędzia (tools), zasoby (resources) i prompty (prompts).

Z perspektywy agenta MCP to dynamiczne rozszerzenie przestrzeni akcji. Bez MCP agent operuje na plikach i terminalu. Z MCP agent sięga po GitHub API, bazy danych, Notion, Slack, generatory obrazów — cokolwiek ktoś opakował w serwer MCP.

Warstwa 3: Skills i hooks

Skills to instrukcje behawioralne ładowane na żądanie (np. /review), hooks to automatyczne reakcje na zdarzenia (np. uruchom formatter po każdym Edit). Oba mechanizmy opisane są szczegółowo w poście #5 (skills) i #6 (hooks) . Tu skupiamy się na warstwie MCP.

MCP pod lupą: jak działa

Jak MCP działa z perspektywy agenta

Mechanikę protokołu MCP — transport stdio/HTTP, trzy prymitywy (Tools, Resources, Prompts), konfigurację serwerów — opisaliśmy szczegółowo w serii MCP dla Claude . Tutaj skupiamy się na tym, co istotne z perspektywy agenta: co model widzi i jak to wpływa na jego rozumowanie.

Klient (Claude Code) na starcie sesji wstrzykuje do kontekstu modelu dwa rodzaje informacji z każdego serwera MCP:

1. Definicje narzędzi — schematy JSON z nazwą, opisem i parametrami. Bez schematu model nie wie, że narzędzie istnieje.
2. Instrukcje behawioralne serwera — tekst mówiący modelowi kiedy i jak używać narzędzi danego serwera (np. "sięgaj po dokumentację nawet gdy znasz bibliotekę — Twoje dane treningowe mogą być nieaktualne").

Z perspektywy modelu narzędzia MCP nie różnią się od wbudowanych — model generuje tool_call, klient routuje wywołanie do właściwego serwera, wynik wraca jako nowa obserwacja. Model nie wie (i nie musi wiedzieć), czy narzędzie jest wbudowane, czy pochodzi z zewnętrznego serwera MCP.

Problem: token overhead

Każde narzędzie MCP ma opis (nazwa, dokumentacja, schemat parametrów JSON). Ten opis jest wstrzykiwany do kontekstu modelu na starcie sesji i pozostaje tam przez całą rozmowę — zajmuje miejsce niezależnie od tego, czy narzędzie zostanie użyte. Model musi "widzieć" narzędzie, żeby go użyć.

Oto skala problemu:

28 000 tokenów to ~14% okna 200k — lub ~2,8% okna 1M (Claude Sonnet 4.6 / Opus 4.6 od marca 2026). W każdej wiadomości. Zanim agent przeczyta choćby jeden plik, kontekst jest już zajęty opisami narzędzi, z których w danej chwili użyje może dwóch.

Rozwiązanie 1: Tool Search (deferred tools)

Claude Code rozwiązuje problem token overhead przez mechanizm Tool Search (deferred tools). Zamiast ładować schematy wszystkich narzędzi MCP na starcie, Claude Code:

1. Rejestruje nazwy narzędzi (bez schematów) — koszt: kilka tokenów per narzędzie
2. Gdy model chce użyć narzędzia, wywołuje ToolSearch(query="...")
3. ToolSearch zwraca pełne schematy dopasowanych narzędzi
4. Dopiero wtedy model może je wywołać

To oznacza, że 27 narzędzi domyślnych toolsetów GitHub MCP kosztuje ~135 tokenów (same nazwy) zamiast ~10 000 (pełne schematy). Schemat jest ładowany dopiero gdy model go potrzebuje.

graph TD
    A[Start sesji] --> B{Ile narzędzi MCP?}
    B -->|<10| C[Ładuj wszystko<br/>mały overhead]
    B -->|10+| D[Deferred: same nazwy<br/>~5 tokenów/narzędzie]
    D --> E[Model potrzebuje narzędzia]
    E --> F[ToolSearch query=...]
    F --> G[Załaduj schemat<br/>jednorazowo]
    G --> H[Model wywołuje narzędzie]

Kiedy Tool Search pomaga

• Masz wiele serwerów MCP z dziesiątkami narzędzi
• Większość narzędzi jest używana rzadko
• Chcesz "mieć pod ręką" GitHub MCP, ale nie płacić ~10 000 tokenów za same schematy

Kiedy nie pomaga

• Masz 2-3 serwery z kilkoma narzędziami (Context7, Sequential Thinking) — overhead jest i tak mały
• Narzędzie jest używane w prawie każdej wiadomości — ładowanie "na żądanie" dodaje opóźnienie

Rozwiązanie 2: Ograniczanie toolsetów

Wiele serwerów MCP pozwala na ograniczenie eksponowanych narzędzi. GitHub MCP ma flagę --toolsets:

claude mcp add github \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_... \
  -- docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  ghcr.io/github/github-mcp-server \
  --toolsets repos,pull_requests

Zamiast ~27 narzędzi (domyślne toolsety) → ~10. Zamiast ~10 000 tokenów → ~4 000. A pokrywa 90% typowych use case'ów.

Analogicznie --read-only wyłącza narzędzia do zapisu (tworzenie PR-ów, komentarzy, merge'ów) — przydatne, gdy Claude ma tylko analizować, nie modyfikować.

Budżet tokenów: ile narzędzi to za dużo?

Okno kontekstowe Claude Sonnet 4.6 / Opus 4.6 to 1M tokenów (od marca 2026; bazowe 200k dla starszych modeli). Oto jak się rozkłada typowa sesja:

Przy 3 serwerach MCP infrastruktura agenta zajmuje ~1.3% okna 1M — marginalnie. Ale przy starszych modelach z oknem 200k te same 13 000 tokenów to już ~6.5%. Problem zaczyna się, gdy dodajesz 10+ serwerów bez Tool Search: przy modelu 200k overhead rośnie do 20-30%, przy 1M do ~3-5% — w obu przypadkach oznacza to niepotrzebne zużycie kontekstu na opisy narzędzi, których agent i tak nie użyje.

Anatomia wywołania narzędzia

Jak wygląda jedno wywołanie narzędzia od strony technicznej:

sequenceDiagram
    participant M as Model
    participant CC as Claude Code
    participant H as Hook PreToolCall
    participant T as Narzędzie/MCP
    participant HP as Hook PostToolCall

    M->>CC: tool_call: Edit(file="src/app.py", ...)
    CC->>H: PreToolCall: Edit
    H-->>CC: OK (lub BLOCKED)
    CC->>CC: Sprawdź permissions
    CC->>CC: Pokaż użytkownikowi (jeśli wymaga approval)
    CC->>T: Wykonaj Edit
    T-->>CC: Wynik (sukces / błąd)
    CC->>HP: PostToolCall: Edit
    HP-->>CC: OK
    CC-->>M: Wynik → nowa obserwacja

Zauważ pięć warstw kontroli:

1. Hooks PreToolCall — programowalna blokada/modyfikacja
2. System permissions — czy narzędzie wymaga potwierdzenia
3. User approval — czy użytkownik pozwolił (jeśli wymaga)
4. Wykonanie — faktyczna akcja
5. Hooks PostToolCall — reakcja na wynik (np. auto-format)

Praktyczne wzorce konfiguracji MCP

Minimalistyczny setup

Always-on:
  - Context7 (dokumentacja bibliotek)

On-demand:
  - GitHub MCP --toolsets repos,pull_requests (gdy pracujesz z PR-ami)

Pełny setup

Always-on:
  - Context7 (dokumentacja)
  - Sequential Thinking (planowanie)

On-demand:
  - GitHub MCP --toolsets repos,pull_requests,issues
  - PostgreSQL MCP (analiza danych)
  - Slack MCP (kontekst z rozmów zespołu)