MCP Servers - łączenie ze światem | Kurs Claude AI

Czym jest MCP

Model Context Protocol (MCP) to otwarty standard łączenia modeli AI z zewnętrznymi narzędziami i źródłami danych.

Architektura:

Host (Claude Code) → Client (protokół MCP) → Server (GitHub, Slack, baza...)

3 prymitywy MCP:

Tools - akcje, które Claude może wykonać (np. „utwórz issue na GitHub”)
Resources - dane, do których Claude ma dostęp (np. „zawartość pliku z Google Drive”)
Prompts - szablony promptów udostępnione przez serwer

Wersja protokołu (stan na 1 października 2026). Od 28 lipca 2026 obowiązuje specyfikacja MCP 2026-07-28. Anthropic nazywa ją potocznie „MCP 2.0” i deklaruje jej obsługę w Claude.

Trzy prymitywy zostały te same. Transporty też: stdio (serwer lokalny uruchamiany jako proces) i Streamable HTTP (serwer zdalny).

Zmieniło się wnętrze. Rdzeń jest bezstanowy (stateless): nie ma powitalnej wymiany komunikatów (handshake) ani sesji, a każde zapytanie samo niesie wersję protokołu. Funkcje Roots, Sampling i Logging dostały status deprecated, czyli są wycofywane. Ten sam status ma stary transport HTTP+SSE (Server-Sent Events, strumień zdarzeń wysyłanych przez serwer).

Dla użytkownika Claude Code to zmiana pod maską. Twórca własnego serwera potrzebuje SDK w wersji 2 dopiero wtedy, gdy chce obsłużyć nową wersję protokołu (ostatnia sekcja lekcji). Serwery zbudowane na starym SDK nadal działają z Claude Code.

Konfiguracja

Główna ścieżka 2026: zdalne serwery HTTP z OAuth

Dostawcy hostują dziś własne serwery MCP w chmurze. Nie instalujesz nic lokalnie - podajesz URL i logujesz się przez OAuth. Dodajesz je jedną komendą:

# Składnia
claude mcp add --transport http <nazwa> <url>

# Przykład: Sentry (monitoring błędów)
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Przykład: GitHub - zdalny serwer, token jako nagłówek
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer TWOJ_GITHUB_PAT"

Serwer wymagający logowania autoryzujesz komendą /mcp w sesji (otwiera flow OAuth 2.0 w przeglądarce) albo claude mcp login <nazwa> z terminala. Poświadczenia czyścisz komendą claude mcp logout <nazwa> - przydaje się przy zmianie konta albo gdy token przestał działać i chcesz wymusić świeże logowanie. Obie komendy terminalowe wymagają wersji 2.1.186 lub nowszej.

Składnia claude mcp add i logowanie przez /mcp działają tak jak na początku roku (stan na 1 października 2026). Od wersji 2.1.265 --transport http sam przechodzi na starszy transport SSE (Server-Sent Events), gdy serwer nie przyjmie HTTP. Z serwerami HTTP, które obsługują specyfikację 2026-07-28, Claude Code rozmawia już w nowej wersji. Z lokalnymi serwerami stdio domyślnie łączy się po staremu. Niczego nie musisz przestawiać.

W pliku konfiguracyjnym zdalny serwer to wpis z "type": "http":

{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

Serwery lokalne (stdio)

Serwery uruchamiane lokalnie konfigurujesz w .mcp.json (root projektu, zakres zespołu) lub przez claude mcp add --transport stdio <nazwa> -- <komenda>:

{
  "mcpServers": {
    "nazwa-serwera": {
      "command": "npx",
      "args": ["-y", "nazwa-paczki"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

Zakres decyduje, kto widzi serwer. claude mcp add bez flagi zapisuje go w ~/.claude.json, tylko dla Ciebie i tylko w bieżącym projekcie (zakres local). Z --scope project serwer trafia do .mcp.json w repozytorium, czyli do całego zespołu. Z --scope user działa we wszystkich Twoich projektach. Plik .mcp.json commitujesz, więc kluczy nie wpisuj w nim wprost. Zapis ${API_KEY} podstawia wartość zmiennej środowiskowej z Twojego komputera. Przed pierwszym użyciem serwerów z .mcp.json Claude Code zapyta o zgodę. To zabezpieczenie, nie błąd.

Zarządzanie w sesji: /mcp - lista serwerów, status połączeń, autoryzacja OAuth. Komenda /mcp reconnect all (wersja 2.1.284 lub nowsza) ponawia naraz połączenie ze wszystkimi serwerami, które nie wstały albo czekają na logowanie.

MCP tool search - narzędzia ładowane leniwie

Dawniej każde narzędzie z każdego serwera lądowało w kontekście od razu na starcie sesji. Dziesięć serwerów po 20 narzędzi to setki definicji zjadających kontekst, zanim napisałeś pierwsze słowo. Dziś domyślnie działa MCP tool search: Claude dostaje tylko nazwy, a pełną definicję narzędzia dociąga wywołaniem ToolSearch dopiero wtedy, gdy go potrzebuje.

Funkcja jest domyślna od modeli Opus 4.5, Sonnet 4.5 i Haiku 4.5 wzwyż. Nie działa na Microsoft Foundry hostowanym na Azure. Claude Code wyłącza ją też, gdy ANTHROPIC_BASE_URL wskazuje serwer pośredniczący (proxy) spoza Anthropic. Wtedy włączysz ją ręcznie zmienną środowiskową ENABLE_TOOL_SEARCH.

Wniosek praktyczny: duży zestaw serwerów przestał być kosztownym błędem, ale nadal podłączaj tylko te, których faktycznie używasz.

Dla organizacji: ustawienie zarządzane managedMcpServers (wymaga 2.1.259 lub nowszej) pozwala administratorowi dostarczyć wszystkim użytkownikom w firmie ten sam zestaw zdalnych serwerów MCP (adresy https). Lokalnych serwerów stdio tą drogą nie rozda. Użytkownicy zachowują też serwery, które dodali sami.

Poza terminalem: konektory z Twojego konta claude.ai działają też w artefaktach (plany Pro, Max, Team, Enterprise; każdy widz łączy własne konto). Serwery dodane w Claude Code (claude mcp add, .mcp.json) dostarczą dane tylko podczas budowania strony. Gotowa strona ich nie wywoła.

Żeby serwer zasilał artefakt na żywo, dodaj go w claude.ai jako własny konektor: Customize > Connectors > Add > Custom > Web (w Team i Enterprise robi to administrator). Serwer musi być dostępny z publicznego internetu, bo claude.ai łączy się z nim z chmury Anthropic. Na Free też dodasz jeden własny konektor, ale skorzystasz z niego w czacie, nie w artefakcie.

W drugą stronę konfiguracja przechodzi sama: konektory z claude.ai widzisz w Claude Code w /mcp, jeśli logujesz się kontem claude.ai. Więcej o stronach z danymi w lekcji o Artifacts.

Popularne MCP Servers

GitHub (oficjalny)

Operacje na repozytoriach, issues, pull requestach.

Rekomendowana ścieżka: serwer zdalny (bez Dockera, bez instalacji) - dokładnie ten z przykładu wyżej:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer TWOJ_GITHUB_PAT"

Token generujesz w GitHub jako fine-grained personal access token z dostępem do wybranych repozytoriów.

Opcja self-hosted: Docker. Ten sam serwer możesz uruchamiać lokalnie w kontenerze:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_xxx..."
      }
    }
  }
}

Token fine-grained zaczyna się od github_pat_, a klasyczny od ghp_. Lokalny serwer GitHub umie też zalogować się przez OAuth w przeglądarce, bez tworzenia tokenu. W Dockerze trzeba wtedy wystawić port zwrotny (instrukcja w repozytorium github/github-mcp-server). Ustawiony token ma pierwszeństwo przed OAuth.

Filesystem

Dostęp do plików poza bieżącym katalogiem.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y",
        "@modelcontextprotocol/server-filesystem",
        "/ścieżka/do/katalogu"]
    }
  }
}

To serwer referencyjny. Twórcy MCP opisują serwery z repozytorium modelcontextprotocol/servers jako przykłady edukacyjne, a nie gotowe rozwiązania produkcyjne. Dawaj mu dostęp tylko do katalogu, którego naprawdę potrzebujesz.

Brave Search

Wyszukiwanie w internecie w czasie rzeczywistym. Uwaga na nazwę paczki - starą referencyjną (@modelcontextprotocol/server-brave-search) przeniesiono do archiwum; aktualny serwer utrzymuje Brave:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y",
        "@brave/brave-search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "BSAxx..."
      }
    }
  }
}

Klucz API wymaga konta w Brave Search API i podania karty płatniczej, nawet na darmowym planie. Według Brave karta służy tylko do weryfikacji i nie jest obciążana. Plan daje $5 darmowych kredytów miesięcznie, czyli około 1000 zapytań przy stawce $5 za 1000 (stan na 1 października 2026).

PostgreSQL i inne bazy danych

Referencyjna paczka @modelcontextprotocol/server-postgres też trafiła do archiwum. Oficjalne docs Claude Code pokazują dziś podłączenie bazy przez serwer DBHub (Postgres, MySQL, SQL Server i inne):

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:haslo@host:5432/analytics"

Dostawcy chmurowych baz (np. Supabase) utrzymują własne serwery MCP - szukaj ich w katalogach z sekcji niżej.

Inne popularne

Slack - wiadomości, kanały
Google Drive - dokumenty
Notion - notatki i bazy
Linear - zarządzanie zadaniami
Sentry - monitoring błędów
Playwright - automatyzacja przeglądarki (serwer Microsoftu @playwright/mcp; dodasz go poleceniem claude mcp add playwright -- npx -y @playwright/mcp@latest). Referencyjny serwer Puppeteer trafił do archiwum.

Instalacja MCP - krok po kroku

Znajdź serwer: w claude.ai otwórz Anthropic Directory (claude.ai/directory, w aplikacji Customize > Connectors). Poza aplikacją katalog przejrzysz w Claude Marketplace (claude.com/marketplace), który działa od 23 września 2026. Anthropic podaje, że zebrał tam ponad 2000 konektorów i pluginów (liczniki na stronie 2 października 2026: 887 konektorów i 341 pluginów). Najszerszą listę ma oficjalny rejestr registry.modelcontextprotocol.io, ale to wersja preview i dane mogą się jeszcze zmieniać. Repozytorium github.com/modelcontextprotocol/servers trzyma dziś tylko kilka serwerów referencyjnych. Anthropic zapowiada na najbliższe tygodnie jedno wspólne miejsce odkrywania rozszerzeń dla Claude i Claude Code, więc te adresy mogą się zmienić.
Dodaj serwer: claude mcp add --transport http <nazwa> <url> (zdalny) lub claude mcp add --transport stdio <nazwa> -- <komenda> (lokalny); alternatywnie edytuj .mcp.json
Ustaw dostępy: OAuth przez /mcp (zdalne) albo klucze API w polu env, najlepiej jako zmienne w postaci ${NAZWA} (lokalne)
Zweryfikuj: /mcp pokazuje status połączenia i liczbę narzędzi. Bez otwierania sesji status pokaże claude mcp list. Zapytaj też: „Jakie narzędzia MCP mam dostępne?”

Tworzenie własnego MCP (podstawy)

Instalacja SDK w wersji 2, zgodnej ze specyfikacją 2026-07-28: npm install @modelcontextprotocol/server zod. Wersja 2 wymaga Node.js 20 lub nowszego oraz Zod 4.2 lub nowszego. Z zod@3 kod się nie skompiluje. W package.json ustaw "type": "module".

Stary pakiet @modelcontextprotocol/sdk (linia 1.x) nadal działa. Poprawki dostaje przez co najmniej 6 miesięcy od premiery wersji 2 (28 lipca 2026, razem ze specyfikacją). Obsługuje jednak tylko starszy protokół 2025-11-25.

Minimalny serwer w TypeScript - klasa McpServer, metoda registerTool i funkcja serveStdio:

import { McpServer } from
  "@modelcontextprotocol/server";
import { serveStdio } from
  "@modelcontextprotocol/server/stdio";
import { z } from "zod";

function createServer() {
  const server = new McpServer({
    name: "moj-serwer",
    version: "1.0.0"
  });

  server.registerTool(
    "powitanie",
    {
      description: "Generuje powitanie",
      inputSchema: z.object({
        imie: z.string().describe("Imię do powitania")
      })
    },
    async ({ imie }) => ({
      content: [{ type: "text", text: `Cześć, ${imie}!` }]
    })
  );

  return server;
}

serveStdio(createServer);

Względem SDK w wersji 1 zmieniają się trzy rzeczy: importy z @modelcontextprotocol/server, schemat opakowany w z.object({...}) oraz serveStdio zamiast pary StdioServerTransport + connect. SDK sam obsługuje tools/list i tools/call. Gołe obiekty pól (bez z.object) jeszcze działają, ale SDK oznacza je jako przestarzałe. Serwer na serveStdio odpowiada w obu wersjach protokołu, więc połączy się z Claude Code i ze starszymi klientami. Para StdioServerTransport + connect ze starszych poradników obsłuży tylko protokół z 2025 roku. Pełny tutorial SDK w wersji 2: ts.sdk.modelcontextprotocol.io/v2/get-started/first-server. Szkielet serwera zbuduje Ci też sam Claude Code: /plugin install mcp-server-dev@claude-plugins-official, a potem /mcp-server-dev:build-mcp-server.

Ćwiczenie praktyczne: Podłącz i przetestuj 2 MCP servers:

Filesystem: Podłącz serwer filesystem z dostępem do jednego katalogu, np. ~/projects, a nie do całego katalogu domowego. Zapytaj Claude Code: „Jakie projekty mam w ~/projects?”

Brave Search: Podłącz Brave Search. Zapytaj: „Jaki jest najnowszy release Node.js?”. Nie chcesz podawać karty w Brave? Podłącz serwer dokumentacji Claude Code, który nie wymaga logowania: claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp. Zapytaj: „Jak dodać serwer MCP w zakresie projektu?”

Bonus: Znajdź i zainstaluj MCP server przydatny w Twojej pracy.

Co dalej

W następnej lekcji poznasz subagentów - sposób na delegowanie zadań do izolowanych kontekstów.