MCP SDK, protokol podlaczania narzedzi do AI

MCP SDK, czyli wspólny sposób podłączania narzędzi do modeli

Model Context Protocol rozwiązuje problem, który przez rok blokował sensowne integracje: każdy asystent miał własny sposób opisywania narzędzi, więc integracja z bazą albo z systemem zgłoszeń wymagała osobnego kodu dla każdego z nich. MCP wprowadza jeden opis, który rozumie każdy zgodny klient.

Co protokół właściwie definiuje

Po stronie serwera znajdują się trzy rodzaje rzeczy, które da się udostępnić, i różnica między nimi decyduje o poprawnym projekcie integracji.

Narzędzia to funkcje, które model może wywołać. Mają nazwę, opis i schemat argumentów, a wykonanie zmienia stan albo pobiera dane wymagające działania. Wysłanie wiadomości, utworzenie zgłoszenia, uruchomienie zapytania to narzędzia.

Zasoby to treść identyfikowana adresem, którą klient może odczytać i włożyć do kontekstu. Plik, rekord, wynik zapytania. Kluczowa różnica polega na tym, że odczyt zasobu nie ma skutków ubocznych, więc klient może go pobrać bez pytania użytkownika o zgodę.

Prompty to gotowe szablony poleceń, które użytkownik wybiera z listy. To najmniej używana część protokołu, a szkoda, bo dobrze opisany szablon oszczędza tłumaczenie modelowi tego samego za każdym razem.

Rozróżnienie między narzędziem a zasobem bywa mylone i warto je rozstrzygnąć na jednym przykładzie. Odczyt pliku z dysku to zasób, bo niczego nie zmienia i klient może go pobrać sam. Zapisanie pliku to narzędzie, bo ma skutek, którego nie da się cofnąć bez świadomej decyzji. Ten podział decyduje o tym, kiedy klient zapyta użytkownika o zgodę, a kiedy zadziała po cichu.

Klient może też oferować możliwości serwerowi. Próbkowanie pozwala serwerowi poprosić o wywołanie modelu. Dopytanie pozwala poprosić użytkownika o brakującą informację w trakcie działania. Korzenie wskazują katalogi, w obrębie których serwer ma pracować.

Dwie z tych trzech rzeczy są jednak na wylocie. Wersja specyfikacji z 28 lipca 2026 roku oznaczyła próbkowanie i korzenie jako wycofywane, razem z osobnym mechanizmem logowania. Działają przez okres przejściowy, ale w nowej integracji katalogi przekazuj argumentem narzędzia albo adresem zasobu, a wywołanie modelu rób bezpośrednio u dostawcy. Dopytanie zostaje i po tej zmianie realizuje się przez żądania wieloprzebiegowe.

Transporty i co zmieniła wersja z lipca 2026

Protokół definiuje dwa sposoby komunikacji i wybór między nimi wynika z miejsca uruchomienia serwera.

Transport przez wejście i wyjście standardowe obsługuje serwery uruchamiane lokalnie jako podproces. Klient startuje program i rozmawia z nim przez strumienie, bez sieci i bez uwierzytelniania. To domyślny wybór dla narzędzi działających na maszynie użytkownika.

Transport przez HTTP obsługuje serwery zdalne. Jeden adres przyjmuje żądania metodą POST i pozwala na strumieniowanie odpowiedzi zdarzeniami serwera, gdy operacja trwa dłużej.

Wersja specyfikacji z 28 lipca 2026 roku zmieniła w tym obszarze rzecz zasadniczą: rdzeń protokołu stał się bezstanowy. Zniknęły sesje na poziomie protokołu razem z nagłówkiem identyfikującym sesję, więc to samo żądanie może obsłużyć dowolna instancja serwera za zwykłym systemem równoważenia obciążenia.

Konsekwencja praktyczna jest duża. Wcześniej serwer zdalny wymagał przypisania klienta do konkretnej instancji, co komplikowało wdrożenie i utrudniało skalowanie. Teraz serwer MCP wdraża się jak zwykłą usługę bezstanową, na przykład na Cloudflare albo w kontenerach za standardowym proxy.

Ta sama wersja przyniosła żądania wieloprzebiegowe, kierowanie po nagłówkach, wyniki list nadające się do buforowania, wzmocnienie autoryzacji oraz formalny mechanizm rozszerzeń. Przy istniejącej integracji sprawdź, którą wersję protokołu obsługuje Twoja biblioteka, bo zmiana bezstanowości dotyka warstwy transportowej.

Pierwszy serwer

npm install @modelcontextprotocol/sdk zod

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { z } from 'zod'

const serwer = new McpServer({ name: 'zamowienia', version: '1.0.0' })

serwer.registerTool(
  'status_zamowienia',
  {
    description: 'Zwraca status zamowienia po numerze w formacie ORD-12345. Wywolaj, gdy uzytkownik pyta o konkretne zamowienie.',
    inputSchema: { numer: z.string().describe('Numer zamowienia, format ORD-12345') },
  },
  async ({ numer }) => {
    const zamowienie = await db.zamowienia.findUnique({ where: { numer } })
    return {
      content: [{ type: 'text', text: zamowienie ? JSON.stringify(zamowienie) : 'nie znaleziono' }],
    }
  }
)

await serwer.connect(new StdioServerTransport())

Rejestrację robi metoda registerTool, przyjmująca nazwę, obiekt konfiguracji i funkcję obsługi. Starszy zapis tool z opisem i schematem podawanymi jako osobne argumenty nadal działa, ale w bibliotece dla TypeScriptu jest oznaczony jako wycofywany, więc w nowym kodzie używaj tej pierwszej postaci.

Opis narzędzia to najważniejsza część tego kodu. Model widzi wyłącznie nazwę, opis i schemat argumentów, więc zdanie mówiące wprost, kiedy narzędzie wywołać, podnosi trafność bardziej niż jakakolwiek zmiana po stronie promptu. Opis w rodzaju „zwraca dane" nie rozstrzyga niczego.

W Pythonie układ jest analogiczny, a schemat argumentów wynika z adnotacji typów funkcji, więc opis powstaje automatycznie z sygnatury i dokumentacji.

Podłączanie do klientów

Konfiguracja po stronie klienta sprowadza się do wskazania, jak uruchomić serwer albo pod jakim adresem go szukać.

{
  "mcpServers": {
    "zamowienia": {
      "command": "node",
      "args": ["/sciezka/do/serwera/index.js"],
      "env": { "DATABASE_URL": "postgres://..." }
    }
  }
}

Ten sam serwer działa w każdym zgodnym kliencie: w aplikacji Claude, w Cursorze, w narzędziach wiersza poleceń i w bibliotekach agentowych. To jest właśnie sens protokołu: integrację piszesz raz.

Serwer działający lokalnie warto przetestować, zanim podepniesz go do asystenta. Narzędzie inspekcyjne z zestawu deweloperskiego uruchamia serwer i pozwala wywołać każdą funkcję ręcznie, co skraca diagnozę z godziny zgadywania do kilku minut. Bez tego kroku błąd w schemacie argumentów objawia się jako niewytłumaczalne zachowanie modelu.

Warto wiedzieć, że część platform udostępnia swoje integracje przez MCP zamiast własnego API. Zapier w ten sposób otwiera setki połączeń z aplikacjami, więc zamiast pisać własny serwer, czasem wystarczy podpiąć istniejący.

Bezpieczeństwo, czyli część, której nie da się pominąć

Serwer MCP daje modelowi możliwość działania, a to zmienia charakter zagrożeń w stosunku do zwykłego czatu.

Pierwsza sprawa to zaufanie do samego serwera. Instalując cudzy serwer, dajesz mu dostęp do tego, co skonfigurujesz: kluczy, plików, baz. Traktuj to jak instalowanie zależności z prawem do wykonywania kodu, bo tym w praktyce jest.

Druga to treści przechodzące przez narzędzia. Dokument, wiadomość albo strona odczytana przez narzędzie może zawierać instrukcje skierowane do modelu, a nie do użytkownika. Wynik narzędzia trzeba traktować jako dane, nigdy jako polecenie, i warto to napisać wprost w instrukcji systemowej.

Trzecia to zakres uprawnień. Serwer czytający zgłoszenia nie potrzebuje prawa do ich usuwania. Osobne poświadczenia o minimalnych uprawnieniach kosztują pięć minut konfiguracji i ograniczają skutki pomyłki modelu. Przy bazie danych to jedyna granica, która się utrzyma, bo ograniczenie wpisane w kod narzędzia da się obejść: w wycofanym już serwerze referencyjnym do PostgreSQL tryb tylko do odczytu znosiło zapytanie zamykające otwartą transakcję.

Czwarta to potwierdzenia przy operacjach nieodwracalnych. Protokół pozwala klientowi zapytać użytkownika przed wykonaniem narzędzia i przy wszystkim, co wysyła wiadomości albo zmienia dane, warto z tego skorzystać.

Wersja z lipca 2026 wzmocniła warstwę autoryzacji, więc przy serwerach zdalnych sprawdź, czy Twoja biblioteka obsługuje aktualne wymagania, zanim wystawisz cokolwiek publicznie.

Jak projektować narzędzia, żeby model z nich korzystał

Serwer działa poprawnie, a model i tak go nie używa albo używa źle. To najczęstsza skarga przy pierwszej integracji i prawie zawsze wynika z opisów, nie z kodu.

Nazwa powinna mówić o działaniu, nie o systemie. Nazwa w rodzaju crm_query nic nie znaczy dla modelu, a znajdz_klienta_po_emailu opisuje, co się wydarzy. Model dopasowuje nazwy do intencji użytkownika, więc im bliżej naturalnego sformułowania, tym lepiej.

Opis powinien zawierać warunek wywołania. Nie „pobiera dane klienta", tylko „wywołaj, gdy użytkownik pyta o dane konkretnego klienta i podał adres e-mail albo identyfikator". To zdanie robi więcej dla trafności niż cała reszta konfiguracji.

Argumenty opisuj z formatem i przykładem. Pole tekstowe nazwane data bez wskazania formatu skończy się datą w trzech różnych zapisach w kolejnych wywołaniach. Adnotacja mówiąca „format ISO, na przykład 2026-07-28" rozwiązuje ten problem raz.

Wynik zwracaj przefiltrowany i opisany. Model radzi sobie lepiej z pięcioma polami opisanymi po ludzku niż z pełną odpowiedzią API. Przy braku wyniku napisz to wprost, zamiast zwracać pustą strukturę, bo model potraktuje ją jako sukces.

Ostatnia rzecz dotyczy granulacji. Jedno narzędzie robiące pięć rzeczy zależnie od parametru jest trudniejsze do trafnego wywołania niż pięć osobnych z jasnymi opisami. Rozdzielaj po intencji użytkownika, nie po strukturze Twojego API.

MCP kontra inne podejścia

Te podejścia można łączyć. Serwer MCP wystawiony na zewnątrz obsłuży asystentów, a ten sam kod wywoływany bezpośrednio obsłuży Twoją aplikację, bez dublowania logiki.

Wybór zależy od tego, ilu klientów ma korzystać z integracji. Przy jednej aplikacji opartej o OpenAI albo Claude wywoływanie funkcji bezpośrednio bywa prostsze. Przy narzędziu, z którego ma korzystać zespół używający różnych asystentów, MCP oszczędza pisanie tego samego trzy razy.

Wdrożenie serwera zdalnego

Serwer lokalny wystarcza do narzędzi osobistych, natomiast integracja używana przez zespół albo przez produkt wymaga wersji zdalnej, a ta stawia inne wymagania.

Zacznij od uwierzytelnienia. Serwer wystawiony pod publicznym adresem bez kontroli dostępu daje każdemu to, co dał modelowi. Wersja specyfikacji z lipca 2026 wzmocniła wymagania w tym obszarze, więc sprawdź, czy Twoja biblioteka je realizuje, zanim wystawisz cokolwiek.

Bezstanowość ułatwia resztę. Skoro żądanie może obsłużyć dowolna instancja, wdrożenie sprowadza się do zwykłej usługi za systemem równoważenia obciążenia, bez przypinania klienta do konkretnego procesu. To dobra wiadomość dla wdrożeń w kontenerach i w środowiskach bezserwerowych.

Ogranicz zakres poświadczeń per instalacja. Jeśli serwer obsługuje wielu klientów, każdy powinien działać na własnych danych dostępowych, a nie na wspólnym kluczu z pełnymi uprawnieniami. Przy jednym kluczu pomyłka w filtrowaniu oznacza dostęp do cudzych danych.

Zaloguj wywołania narzędzi razem z tym, kto je wywołał i z jakimi argumentami. Przy diagnozowaniu zgłoszenia „asystent zrobił coś dziwnego" to jedyne źródło odpowiedzi, a przy narzędziach zmieniających dane bywa też wymogiem audytowym.

Ostatnia rzecz to wersjonowanie. Zmiana schematu argumentów albo znaczenia narzędzia wpływa na wszystkich podłączonych klientów naraz, więc traktuj opis narzędzia jak publiczne API, a nie jak wewnętrzny szczegół implementacji.

Typowe błędy

Pierwszy to ogólne opisy narzędzi. Model wybiera narzędzie na podstawie opisu, więc „zarządza danymi" gwarantuje losowe wywołania albo ich brak.

Drugi to udostępnianie zbyt wielu narzędzi naraz. Trzydzieści funkcji w jednym serwerze wydłuża prompt przy każdym wywołaniu i zwiększa liczbę pomyłek w wyborze. Podziel je na kilka serwerów tematycznych.

Trzeci to zwracanie surowych odpowiedzi API. Model dostaje wtedy trzysta linii JSON-a, z których potrzebuje trzech pól. Przefiltruj wynik po swojej stronie, bo to obniża koszt i poprawia trafność.

Czwarty to brak obsługi błędów. Narzędzie, które rzuca wyjątkiem zamiast zwrócić czytelny komunikat, zatrzymuje agenta bez informacji, co poszło nie tak.

Piąty to ignorowanie wersji protokołu przy aktualizacji. Zmiana w warstwie transportu potrafi rozłączyć klientów opartych o starszą bibliotekę, więc listę zmian warto przeczytać przed podniesieniem wersji.

Szósty to trzymanie kluczy w konfiguracji klienta w postaci jawnej. Plik konfiguracyjny bywa synchronizowany albo trafia do repozytorium, więc sekrety lepiej podawać przez zmienne środowiskowe systemu.

FAQ

Czym MCP różni się od wywoływania funkcji?

Wywoływanie funkcji to mechanizm w API konkretnego dostawcy: opisujesz narzędzia w formacie tego dostawcy i obsługujesz je w swoim kodzie. MCP to protokół ponad tym, dzięki któremu ten sam serwer działa z każdym zgodnym klientem bez zmian. Pod spodem klient i tak korzysta z wywoływania funkcji.

Czy muszę pisać serwer w konkretnym języku?

Nie, biblioteki istnieją dla kilku języków, a protokół opiera się na wymianie komunikatów, więc implementacja w dowolnym środowisku jest możliwa. Najbardziej dojrzałe wsparcie mają TypeScript i Python.

Co zmieniła wersja 2026-07-28?

Najważniejsza zmiana to bezstanowy rdzeń protokołu: zniknęły sesje i nagłówek je identyfikujący, więc serwer zdalny skaluje się jak zwykła usługa bezstanowa. Doszły też żądania wieloprzebiegowe, kierowanie po nagłówkach, buforowanie list, wzmocniona autoryzacja i formalne rozszerzenia. Ta sama wersja oznaczyła próbkowanie, korzenie i logowanie jako wycofywane, więc nowe implementacje nie powinny ich już dodawać.

Czy serwer MCP jest bezpieczny?

Sam protokół nie rozwiązuje kwestii zaufania. Instalując cudzy serwer, dajesz mu dostęp do skonfigurowanych zasobów, więc traktuj to jak zależność z prawem wykonywania kodu. Ogranicz uprawnienia poświadczeń, wymagaj potwierdzenia przy operacjach nieodwracalnych i traktuj wyniki narzędzi jako dane, nie polecenia.

Od czego zacząć?

Od jednego narzędzia rozwiązującego konkretny problem, który powtarzasz ręcznie. Serwer z jedną funkcją i dobrym opisem daje więcej niż dziesięć funkcji opisanych pobieżnie, a przy okazji pokazuje, jak model faktycznie interpretuje Twoje opisy. Gotowe integracje warto podpiąć zamiast pisać, na przykład przez LangChain albo przez serwery udostępniane przez platformy automatyzacji.

Specyfikacja stoi na modelcontextprotocol.io, a opis zmian na blogu projektu.