Własny serwer MCP: kiedy go budować, w czym i jak zacząć
MCP (Model Context Protocol) to otwarty standard, przez który aplikacja AI, na przykład Claude Desktop albo VS Code, sięga do danych i funkcji Twojej firmy; własny serwer MCP ma sens, gdy masz własny system (bazę, ERP, sklep), a producent nie dał do niego gotowego serwera. Jak go zrobić: wybierz jedno z dziesięciu oficjalnych SDK w języku reszty systemu, zacznij od transportu stdio i trzech narzędzi tylko do odczytu, przetestuj je w MCP Inspectorze, podłącz do hosta, a HTTP z OAuth 2.1 dołóż dopiero wtedy, gdy serwer ma działać zdalnie.
- Obowiązująca wersja specyfikacji MCP to 2026-07-28.
- Oficjalnych SDK MCP jest dziesięć, a w tierze 1 jest sześć: TypeScript, Python, C#, Go, Rust i Ruby.
- Pierwszy serwer MCP zacznij od transportu stdio i trzech narzędzi wyłącznie do odczytu, z nazwanymi operacjami, limitami wywołań i dziennikiem.
- Autoryzacja jest w MCP opcjonalna; jeśli serwer na HTTP ją wdraża, specyfikacja zaleca oprzeć ją na OAuth 2.1, a serwer musi wtedy sprawdzać, czy token wydano właśnie dla niego.
Czym jest MCP i co dokładnie standaryzuje
MCP opisuje format wiadomości, metody i sposób, w jaki serwer przedstawia swoje możliwości. Nie opisuje tego, jak aplikacja korzysta z modelu.
MCP to otwarty protokół, który — jak ujmuje to specyfikacja — umożliwia płynną integrację między aplikacjami opartymi na modelach językowych a zewnętrznymi źródłami danych i narzędziami. Standaryzuje trzy rzeczy: format wiadomości (JSON-RPC 2.0), zestaw metod, którymi klient odkrywa i wywołuje możliwości serwera, oraz sposób, w jaki te możliwości się opisuje. Dokumentacja dopowiada wprost, czego MCP nie robi: nie dyktuje, jak aplikacja używa modelu ani jak zarządza kontekstem. To ważne rozróżnienie: serwer daje modelowi dostęp do operacji, ale o tym, kiedy i po co model z nich skorzysta, decyduje aplikacja, a nie protokół. Cytaty i wymogi w tym przewodniku pochodzą ze specyfikacji 2026-07-28, z dokumentacji na modelcontextprotocol.io i z README oficjalnych SDK; adresy z datą sprawdzenia są w źródłach na końcu strony.
Role są trzy i warto je nazywać precyzyjnie, bo w dokumentacji pojawiają się na każdym kroku. Host to aplikacja AI, która koordynuje połączenia. Klient to komponent wewnątrz hosta, utrzymujący dedykowane połączenie — jeden na każdy serwer. Serwer to program dostarczający kontekst i możliwości, niezależnie od tego, gdzie działa. Ten sam program uruchomiony lokalnie przez stdio nazywamy serwerem lokalnym, a wystawiony pod adresem HTTP — zdalnym.
Według dokumentacji architektury wersja 2026-07-28 zmieniła rzecz, o której trzeba wiedzieć, zanim sięgniesz po starszy poradnik. Protokół jest teraz bezstanowy: każde żądanie niesie w polu _meta wersję protokołu i możliwości klienta, więc serwer nie wnioskuje niczego z wcześniejszych żądań. Miejsce obowiązkowego uścisku dłoni initialize zajęło żądanie server/discover, które w jednej odpowiedzi zwraca obsługiwane wersje, możliwości i tożsamość serwera. Dla klienta wywołanie go jest opcjonalne — może wysłać dowolne żądanie od razu i obsłużyć ewentualny błąd wersji — ale dokumentacja nazywa server/discover żądaniem obowiązkowym po stronie serwera. Pisząc dziś nową implementację, musisz je obsłużyć.
Kiedy NIE budować własnego serwera
W tych pięciu sytuacjach lepiej sięgnąć po gotowy serwer, skrypt albo zwykłe wywołanie funkcji w kodzie aplikacji.
- Producent ma już gotowy serwerProducent systemu, do którego chcesz sięgnąć, może mieć już gotowy serwer; dokumentacja architektury protokołu podaje jako przykład zdalny serwer Sentry. Zacznij od oficjalnego rejestru serwerów. Jego README porównuje rejestr do sklepu z aplikacjami, choć to wciąż wersja zapoznawcza. Repozytorium implementacji referencyjnych też warto przejrzeć, ale ono samo zastrzega, że zawiera przykłady, a nie serwery gotowe do produkcji. Producent aktualizuje swój serwer razem ze swoim API, a Ty musiałbyś śledzić te zmiany sam.
- Wystarczy zwykła integracjaJeśli ścieżka jest z góry znana i stała — „co noc pobierz raport, wrzuć do arkusza, wyślij mail” — to jest zadanie dla skryptu albo webhooka, nie dla protokołu, w którym o kolejności kroków decyduje model. MCP ma sens wtedy, gdy kolejność i dobór kroków zależą od pytania użytkownika.
- Masz jedno narzędzie i jednego klientaGłówna korzyść z protokołu to to, że raz opisane możliwości działają w wielu hostach; specyfikacja wskazuje jako inspirację Language Server Protocol, który ujednolicił obsługę języków w narzędziach programistycznych. Przy jednym narzędziu i jednym miejscu użycia zwykłe wywołanie funkcji w kodzie aplikacji będzie prostsze w utrzymaniu.
- Nikt nie może odpowiadać za utrzymanieTaki serwer trzeba aktualizować razem ze specyfikacją i z SDK. Według strony o wersjonowaniu funkcja oznaczona jako przestarzała zostaje w specyfikacji co najmniej 12 miesięcy, a w trybie przyspieszonego usunięcia co najmniej 90 dni, więc ktoś powinien raz na kwartał przejrzeć rejestr przestarzałych funkcji i w razie potrzeby podbić bibliotekę. Jeśli w firmie nie ma takiej osoby, wybierz gotowy serwer albo zleć utrzymanie.
- Chcesz „opakować” cudze API cudzym tokenemTo nie jest kwestia gustu architektonicznego, tylko zakazu: specyfikacja autoryzacji mówi, że serwer nie może przyjmować tokenów, które nie zostały wydane dla niego, a dokumentacja bezpieczeństwa nazywa przekazywanie ich dalej antywzorcem. Jeśli Twój pomysł na integrację polega na przyjęciu tokena klienta i podaniu go dalej, pomysł trzeba przeprojektować, zanim powstanie pierwsza linia kodu.
W czym to napisać: dziesięć oficjalnych SDK
To jest sedno pytania „TypeScript, .NET czy coś innego”. Oficjalna lista SDK na stronie modelcontextprotocol.io obejmuje dziesięć języków i żaden z nich nie jest „tym właściwym” dla każdego.
Wybór idzie za tym, w czym stoi reszta Twojego systemu, bo serwer to cienka warstwa nad kodem, który już masz — ma sięgać do Twojej bazy, Twojego systemu magazynowego, Twoich uprawnień. Przepisywanie tej logiki w innym języku tylko po to, żeby użyć modnego SDK, to dodatkowa praca i drugi kod do utrzymania, a na końcu dostajesz te same trzy narzędzia.
Strona „SDK Tiering System” w dokumentacji MCP dzieli SDK na trzy tiery i opisuje je zobowiązaniami, a nie wrażeniami. Tier 1: sto procent testów zgodności, nowe funkcje protokołu przed wydaniem nowej wersji specyfikacji, triaż zgłoszeń w dwa dni robocze, krytyczne błędy w siedem dni, wymagane stabilne wydanie, dokumentacja z przykładami do wszystkich funkcji, opublikowana polityka zależności i mapa drogowa. Tier 2: osiemdziesiąt procent testów, nowe funkcje w ciągu sześciu miesięcy, triaż w miesiąc, krytyczne błędy w dwa tygodnie. Tier 3: brak minimum testów, brak zobowiązania czasowego co do nowych funkcji, brak wymogu triażu i brak wymogu stabilnego wydania.
Tiery nie są nadane raz na zawsze i to jest argument, który warto znać, wybierając na dłużej. Ta sama strona opisuje degradację: SDK może spaść o tier, jeśli testy zgodności na najnowszym stabilnym wydaniu padają nieprzerwanie przez cztery tygodnie (dla tieru 1 wystarczy jeden test, dla tieru 2 — ponad dwadzieścia procent), albo jeśli zgłoszenia zostają bez reakcji przez dwa miesiące. Tier na liście wynika więc z wyników testów i z reakcji na zgłoszenia, a nie z deklaracji autorów biblioteki.
Szczegóły z README poszczególnych repozytoriów zebrałem w tabeli poniżej: od której wersji biblioteka obsługuje specyfikację 2026-07-28, jak podzielono pakiety i które SDK same nazywają się eksperymentalnymi. Według oficjalnej listy SDK w tierze 1 jest sześć bibliotek, łącznie z Ruby, a w tierze 2 sama Java.
| Język | Tier | Kiedy ma sens | Na co uważać |
|---|---|---|---|
| TypeScript | 1 | Backend w Node, zespół frontendowy, serwer uruchamiany przez npx u użytkownika | Linia v2 (wydana 27 lipca 2026 r.) rozbita na dwa pakiety: @modelcontextprotocol/server i @modelcontextprotocol/client; README obiecuje dla v1.x poprawki błędów i bezpieczeństwa przez co najmniej sześć miesięcy od wydania v2 |
| Python | 1 | Analityka, integracje z danymi, zespół, który i tak pisze skrypty w Pythonie | v2 to obecna stabilna linia (na PyPI 2.3.0 z 2 października 2026 r.), obsługuje jednocześnie 2026-07-28 i poprzednią wersję; v1.x jest w trybie utrzymania bez podanej daty końca. Bez ograniczenia wersji w zależnościach migracja zaskoczy Cię przy najbliższym buildzie; dokumentacja ma osobny przewodnik migracji |
| C# | 1 | Firmy stojące na .NET, integracja z istniejącym backendem lub systemem ERP | Utrzymywany we współpracy z Microsoftem; oficjalny przewodnik instaluje pakiet z flagą --prerelease; pakiety NuGet: ModelContextProtocol.Core, główny ModelContextProtocol, ModelContextProtocol.AspNetCore dla serwerów HTTP i osobne pakiety rozszerzeń Apps i Tasks |
| Go | 1 | Usługi sieciowe, jeden binarny plik do wdrożenia, serwery zdalne | Utrzymywany we współpracy z Google; tabela zgodności w README: specyfikację 2026-07-28 obsługują wersje od v1.7.0 |
| Rust | 1 | Systemy o wysokich wymaganiach wydajnościowych, narzędzia natywne | Crate rmcp, implementacja oparta na środowisku tokio; obsługuje 2026-07-28 i zachowuje zgodność z 2025-11-25 oraz wcześniejszymi; przejście na 3.x ma osobny przewodnik migracji |
| Ruby | 1 | Istniejąca aplikacja w Rails, do której serwer ma sięgać | Gem mcp, obsługa stdio i Streamable HTTP oraz integracja z Rails; dokumentacja gema 1.7.0 wymienia 2026-07-28 wśród obsługiwanych wersji, ale domyślną nadal jest 2025-11-25 z uściskiem dłoni — ustaw wersję świadomie |
| Java | 2 | Duże wdrożenia korporacyjne, zespoły na Springu | Tier 2 oznacza nowe funkcje protokołu w ciągu sześciu miesięcy, nie od razu; repozytorium deklaruje Javę 17+, dystrybucja przez Maven Central, integracja przez Spring AI |
| Kotlin | 3 | Zespoły piszące w Kotlinie; jedna baza kodu dla JVM, Native, JS i Wasm | Tier 3 — brak zobowiązań czasowych co do nowych funkcji protokołu; dystrybucja przez Maven Central |
| PHP | 3 | Serwer przy istniejącej aplikacji PHP, na przykład w Symfony albo Drupalu | Tier 3; projekt prowadzony wspólnie przez Fundację PHP i Symfony, sam określa się jako eksperymentalny do pierwszego wydania głównego |
| Swift | 3 | Narzędzia natywne dla macOS i iOS | Tier 3, bez minimalnego progu testów zgodności; README deklaruje zgodność z wersją specyfikacji 2025-11-25, nie 2026-07-28 — sprawdź stan repozytorium, zanim oprzesz na nim serwer |
Jak zacząć: krok po kroku od pierwszego narzędzia
Pierwsza wersja ma odpowiedzieć na jedno pytanie: czy model trafnie wybiera narzędzie na podstawie Twojego opisu. Dlatego nie ma w niej zapisu do danych, wystawienia do sieci ani OAuth-a.
- Wybierz SDK zgodne z resztą systemuBierz to, w czym już utrzymujesz kod; tabela w poprzedniej sekcji podpowiada, na co uważać przy każdym SDK. Polecenia instalacji z oficjalnego przewodnika: dla C#
dotnet add package ModelContextProtocol --prerelease, dla TypeScriptunpm install @modelcontextprotocol/server zod, dla Pythonauv add "mcp[cli]". - Zacznij od transportu stdioSerwer uruchamiany lokalnie jako proces potomny: bez hostingu, bez OAuth-a, z poświadczeniami w zmiennych środowiskowych, tak jak przewiduje specyfikacja autoryzacji dla stdio. Dokumentacja bezpieczeństwa zaleca stdio przy pracy lokalnej, bo wtedy z procesem rozmawia tylko klient MCP, który go uruchomił.
- W TypeScripcie uruchamiaj serwer przez serveStdio()Oficjalny przewodnik dla SDK v2 uruchamia serwer funkcją
serveStdio()z@modelcontextprotocol/server/stdioi wyjaśnia dlaczego: funkcja negocjuje wersję protokołu z każdym klientem, więc ten sam program odpowie klientom 2026-07-28 i klientom ze starszym uściskiem dłoniinitialize. Przewodnik ostrzega też, że ręczneserver.connect(new StdioServerTransport())nadal się kompiluje, ale tak uruchomiony obsługuje tylko klientów z epoki 2025. - Zdefiniuj trzy narzędzia wyłącznie do odczytuTypowy komplet: wyszukanie rekordu po identyfikatorze, lista rekordów z ostatnich N dni i podsumowanie jednego zbioru. Każde z nazwanym, wąskim
inputSchema. Zero zapisu, zero usuwania, zero dowolnego SQL-a. W Pythonie narzędzie to funkcja z dekoratorem@mcp.tool(), a SDK buduje jej definicję z podpowiedzi typów i docstringu. W TypeScripcie rejestrujesz je wywołaniemserver.registerTool()z nazwą, opisem i schematem wejścia w zod; szkic całości z jednym takim narzędziem jest w listingu pod krokami. - Napisz opisy jak dla nowego pracownikaOpis narzędzia to wejście modelu: napisz, co robi, kiedy go użyć, a kiedy nie, i co znaczą parametry. Nazwy trzymaj w granicach zalecanych przez specyfikację — od 1 do 128 znaków, litery ASCII, cyfry, podkreślenie, myślnik i kropka, bez spacji — i pilnuj unikalności w obrębie serwera.
- Loguj wyłącznie na stderrPrzy stdio każdy zapis na stdout, który nie jest wiadomością MCP, psuje strumień JSON-RPC. Uwaga na częste nieporozumienie: ten zakaz dotyczy stdio. Przy transporcie HTTP dokumentacja mówi wprost, że logowanie na standardowe wyjście jest w porządku, bo nie koliduje z odpowiedziami HTTP.
- Przetestuj w MCP Inspectorze, zanim podłączysz do hostaInspector to oficjalne narzędzie projektu, opisane jako wizualne narzędzie do testowania serwerów MCP; ma też tryb wiersza poleceń (
--cli). Pozwala zobaczyć listę narzędzi i wywołać je ręcznie, bez pośrednictwa modelu — czyli oddzielić błąd w kodzie od błędu w opisie. Uwaga na pułapkę opisaną w dokumentacji Inspectora: domyślnie łączy się on w trybielegacy, czyli starym uściskiem dłoniinitialize. Żeby sprawdzić odpowiedzi dla klientów 2026-07-28, uruchom Inspector z--protocol-era modern, a potem raz jeszcze w trybielegacy, jeśli obiecujesz zgodność wstecz. - Podłącz serwer do hostaW Claude Desktop dopisujesz serwer w kluczu
mcpServersplikuclaude_desktop_config.json(na macOS w katalogu~/Library/Application Support/Claude/, na Windows w folderze Claude w%AppData%): nazwę,commandiargsz bezwzględną ścieżką do programu. Po zapisaniu pliku uruchom aplikację ponownie. Inne hosty, na przykład VS Code, mają własny format konfiguracji, opisany w ich dokumentacji. - Sprawdź zachowanie przy niepowodzeniuZanim pokażesz go komukolwiek, wywołaj narzędzie ze złym argumentem i zobacz, co wraca. Błąd wykonania ma wrócić w wyniku z
isError: truei treścią, z której model zrozumie, co poprawić. Sprawdź też, co się stanie, gdy proces padnie — specyfikacja zakłada, że klient go zrestartuje, a żądania w locie przepadną i klient może je ponowić na nowym procesie. Dlatego narzędzie, które coś zapisuje, powinno znieść powtórzone wywołanie bez podwójnego skutku. - Gdy serwer ma być zdalny: wystaw go na HTTPSerwer zdalny udostępnia jedną ścieżkę przyjmującą POST, na przykład
/mcp; w C# służy do tego pakietModelContextProtocol.AspNetCore. Według specyfikacji musi sprawdzać nagłówekOrigini odrzucać nieprawidłowy kodem 403, a przy pracy lokalnej powinien nasłuchiwać tylko na 127.0.0.1. Implementacja obsługująca wyłącznie wersję 2026-07-28 odpowiada na GET i DELETE kodem 405. Jeśli stoi za reverse proxy, na przykład nginx, odpowiedzi strumieniowe SSE powinny mieć nagłówekX-Accel-Buffering: no, żeby proxy ich nie wstrzymywało. Wersja dostępna publicznie potrzebuje jeszcze autoryzacji, najlepiej według zalecanego przez specyfikację OAuth 2.1, ze sprawdzaniem, czy token wydano właśnie dla niej. - Zapis dopiero na końcuOperacje zapisu to osobna decyzja z własnym kosztem: osobne poświadczenia, potwierdzenie przez użytkownika przed wykonaniem i wpis w dzienniku. Dokładaj je pojedynczo, dopiero gdy wersja tylko do odczytu działa i wiesz, o co ludzie naprawdę pytają.
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";
// serveStdio wywołuje tę funkcję, gdy potrzebuje instancji,
// więc za każdym razem zwracamy nowy serwer.
function createServer() {
const server = new McpServer({ name: "zamowienia", version: "1.0.0" });
server.registerTool(
"order_get_by_number",
{
description:
"Zwraca jedno zamówienie po numerze. Użyj, gdy użytkownik poda numer zamówienia. Tylko odczyt.",
inputSchema: z.object({
number: z.string().max(40).describe("Numer zamówienia, np. ZK/123/2026"),
}),
},
async ({ number }) => {
const order = await findOrder(number);
if (!order) {
// Błąd wykonania wraca w wyniku, żeby model mógł poprawić argument.
return { content: [{ type: "text", text: "Nie ma zamówienia " + number }], isError: true };
}
return { content: [{ type: "text", text: JSON.stringify(order) }] };
},
);
return server;
}
serveStdio(createServer, {
onerror: (error) => console.error("Błąd serwera MCP:", error), // stderr, nigdy stdout
});
Ile to kosztuje i od czego zależy cena
Sam protokół nic nie kosztuje. Płacisz za pracę nad dostępem do Twoich danych: listę operacji, uprawnienia, testy i utrzymanie.
Jeśli budujesz we własnym zespole, płacisz czasem programistów. SDK i MCP Inspector to otwarte projekty na GitHubie, bez opłat licencyjnych. Hosting dochodzi tylko przy wersji zdalnej, bo wersja na stdio działa na komputerze użytkownika. Osobno płacisz dostawcy modelu za asystenta, z którego korzystasz.
Jeśli zlecasz budowę, porównuj oferty po zakresie, a nie po samej kwocie. Rozsądny pierwszy etap to lista narzędzi uzgodniona z osobami, które będą zadawać pytania, serwer podłączony do jednego źródła danych i na start tylko do odczytu, uwierzytelnianie, limity zapytań, dziennik wywołań oraz testy na prawdziwych pytaniach z firmy. Tak wygląda zakres mojej usługi, a widełki netto podaję w cenniku.
Cenę podnoszą operacje zapisu do systemów produkcyjnych (osobny etap, z potwierdzaniem przez człowieka), każde kolejne źródło danych, źródło bez API albo z dokumentacją, którą trzeba odtworzyć z zachowania systemu, oraz wymagania audytowe: rozdzielone role, retencja dziennika, środowisko testowe obok produkcji. Szczegóły zakresu są na stronie serwery MCP.
Czym MCP różni się od zwykłego REST API
Różnica nie leży w formacie wiadomości. Leży w tym, kto decyduje, które wywołanie wykonać.
W zwykłym REST API to Twój kod decyduje, które wywołanie wykonać. Piszesz warunki, piszesz kolejność kroków, znasz z góry ścieżkę. W MCP tę decyzję podejmuje model, na podstawie opisów, które serwer sam o sobie publikuje. Specyfikacja nazywa narzędzia wprost sterowanymi przez model: model odkrywa je i wywołuje automatycznie na podstawie kontekstu rozmowy i tego, o co poprosił użytkownik.
Konsekwencje są praktyczne i nieprzyjemne, jeśli się ich nie przewidzi. Opis narzędzia przestaje być dokumentacją dla programisty, a staje się częścią wejścia modelu — źle napisany opis to błędne wywołania. Schemat wejścia (inputSchema w formacie JSON Schema, domyślnie w wersji 2020-12) nie jest ozdobą, tylko jedyną barierą między zdaniem po polsku a wywołaniem na Twoich danych. I nie ma stałej kolejności: model może wywołać narzędzie numer trzy, nie wywoławszy wcześniej pierwszego i drugiego. Każde narzędzie musi być bezpieczne samo w sobie, bez założeń o tym, co zdarzyło się przed nim.
Do tego dochodzi drugi brak stanu — protokolarny. Specyfikacja mówi wprost, że MCP nie ma sesji na poziomie protokołu, więc serwer nie może opierać się na domyślnym stanie połączenia, żeby powiązać jedno wywołanie z następnym. Koszyk, otwarty kontekst przeglądarki, transakcja bazodanowa — wszystko to trzeba prowadzić przez jawny uchwyt zwracany przez narzędzie tworzące i przyjmowany z powrotem jako zwykły argument.
Dlatego MCP nie zastępuje REST API. Jest warstwą nad nim — świadomie zawężoną, opisaną językiem naturalnym i pomyślaną tak, żeby decyzję o wywołaniu mógł podjąć ktoś, kto nie czytał Twojej dokumentacji.
Trzy prymitywy: narzędzia, zasoby, prompty
Dokumentacja dzieli je według tego, kto nimi steruje: narzędziami model, zasobami aplikacja, a promptami użytkownik.
Narzędzia (tools/list, tools/call) to funkcje wykonujące działanie: zapytanie do bazy, wywołanie API, zapis pliku. Steruje nimi model. Definicja zawiera nazwę, opcjonalny title do wyświetlenia, opis, inputSchema i opcjonalnie outputSchema. Przy podanym outputSchema serwer musi zwracać dane zgodne ze schematem, a klient powinien je walidować. To twardy kontrakt na wyjściu narzędzia i warto z niego korzystać.
Zasoby (resources/list, resources/templates/list, resources/read) to pasywne dane tylko do odczytu, identyfikowane przez URI. Bywają stałe (calendar://events/2024) albo parametryzowane szablonem (travel://activities/{city}/{category}). Steruje nimi aplikacja: to host decyduje, co wciągnąć do kontekstu i w jakiej postaci — czy przepuścić przez wyszukiwanie, czy podać modelowi surowo.
Prompty (prompts/list, prompts/get) to parametryzowane szablony pracy. Steruje nimi użytkownik — dokumentacja mówi o jawnym wywołaniu i wymienia typowe interfejsy: komendy ze slashem, palety poleceń, dedykowane przyciski.
Przegląd specyfikacji 2026-07-28 wymienia po stronie klienta już tylko elicitation, czyli możliwość dopytania użytkownika w trakcie obsługi żądania. Rejestr przestarzałych funkcji tej wersji wpisuje na listę sampling (proszenie klienta o uzupełnienie modelem), roots i logging. W zamian kieruje nowe wdrożenia do bezpośredniej integracji z API dostawcy modelu, do przekazywania katalogów i plików w parametrach narzędzi oraz do logów na stderr albo do OpenTelemetry. Według tego samego rejestru te funkcje mogą zniknąć najwcześniej w pierwszej wersji specyfikacji wydanej 28 lipca 2027 r. lub później. Jeśli projektujesz serwer wokół samplingu, projektujesz go wokół funkcji na wylocie.
Praktyczna rada na start: zacznij od narzędzi, bo z nich korzysta sam model, niezależnie od interfejsu hosta. Czy dany host pokazuje zasoby i prompty, sprawdź w jego dokumentacji. Projekt nie publikuje już ogólnej tabeli, który klient obsługuje które funkcje rdzenia; taką tabelę prowadzi tylko dla rozszerzeń.
Transport: stdio kontra Streamable HTTP
Specyfikacja definiuje dwa transporty i to naprawdę jest wybór binarny.
Stdio: klient uruchamia serwer jako proces potomny i rozmawia z nim przez standardowe strumienie. Jedna wiadomość JSON-RPC na linię, bez znaków nowej linii w środku. Obowiązuje tu twarda reguła: serwer nie może wypisać na stdout niczego, co nie jest poprawną wiadomością MCP. Każde print(), console.log(), System.out.println(), println() czy Console.WriteLine() uszkadza wiadomości JSON-RPC i, jak ostrzega dokumentacja, psuje działanie serwera. Logi idą na stderr: specyfikacja wprost pozwala serwerowi pisać tam ciągi UTF-8 w celach informacyjnych, debugowych i błędowych, a klient nie powinien traktować wyjścia na stderr jako sygnału awarii.
Streamable HTTP: serwer wystawia jedną ścieżkę HTTP przyjmującą POST. Każde żądanie to osobny POST, a odpowiedź to albo pojedynczy obiekt JSON, albo strumień SSE związany z tym jednym żądaniem. W wersji 2026-07-28 usunięto samodzielny strumień GET i sesje na poziomie protokołu, a strumienie nie są wznawialne przez Last-Event-ID. Długo żyjące powiadomienia o zmianach dostaje się przez osobne żądanie subscriptions/listen, którego odpowiedź jest strumieniem SSE pozostającym otwartym. Serwer obsługujący wyłącznie tę wersję ma na GET i DELETE odpowiadać kodem 405, ignorować Mcp-Session-Id i ignorować Last-Event-ID.
Kiedy co: stdio, gdy serwer ma działać na maszynie użytkownika i obsługiwać jednego klienta — to domyślny wybór dla narzędzi deweloperskich i dla wszystkiego, co sięga do lokalnych plików. Streamable HTTP, gdy serwer ma stać u Ciebie i obsługiwać wielu klientów; dokumentacja architektury opisuje ten podział dokładnie w ten sposób.
Ten wybór pociąga za sobą model uwierzytelniania — ale nie tak ostro, jak się to zwykle powtarza. Specyfikacja autoryzacji zaczyna się od zdania, że autoryzacja jest opcjonalna: implementacje na transporcie HTTP powinny się do niej stosować, implementacje na stdio nie powinny i mają pobierać poświadczenia ze środowiska. Dokumentacja architektury wymienia dla Streamable HTTP standardowe metody uwierzytelniania HTTP — tokeny bearer, klucze API i własne nagłówki — i dopiero rekomenduje OAuth jako sposób zdobycia tokena. Praktyczny wniosek jest więc dwuczłonowy: przy stdio klucz do bazy siedzi w zmiennej środowiskowej procesu, a przy HTTP wybierasz świadomie — jeśli serwer jest zdalny i dostępny publicznie, sięgnij po ścieżkę zalecaną przez specyfikację, czyli OAuth 2.1 z walidacją odbiorcy tokena, opisaną w sekcji o uwierzytelnianiu niżej.
Serwer lokalny kontra zdalny
Serwer lokalny działa na komputerze użytkownika i ma jego uprawnienia. Zdalny stoi w sieci, więc trzeba go uwierzytelnić. Z tego biorą się inne ryzyka i inny koszt utrzymania.
Lokalny serwer MCP uruchamia się na komputerze użytkownika, najczęściej przez stdio, i obsługuje jednego klienta. Zdalny działa na Twojej infrastrukturze, jest dostępny pod adresem URL przez Streamable HTTP i może obsługiwać wielu klientów naraz. Lokalny jest prostszy: nie wymaga hostingu i nie wystawia Twojej bazy do internetu. Ma jednak uprawnienia użytkownika, a każdy użytkownik musi go u siebie zainstalować i aktualizować.
Dokumentacja bezpieczeństwa traktuje serwery lokalne jako osobny rozdział i wymienia trzy scenariusze ataku: złośliwa komenda startowa wstrzyknięta w konfigurację klienta, złośliwy ładunek w samym serwerze oraz dostanie się przez DNS rebinding do niezabezpieczonego serwera zostawionego na localhost. Lista zaleceń dla klientów jest konkretna: pokazać pełną, nieskróconą komendę przed wykonaniem, oznaczyć ją jako operację potencjalnie niebezpieczną, wymagać jawnej zgody, ostrzec, że serwer MCP działa z tymi samymi uprawnieniami co klient, i uruchamiać serwery w piaskownicy o minimalnych uprawnieniach.
Autorom serwerów przeznaczonych do uruchamiania lokalnie ta sama dokumentacja radzi coś, co warto zapamiętać: używaj transportu stdio, żeby ograniczyć dostęp wyłącznie do klienta MCP. Jeśli mimo wszystko wystawiasz serwer lokalny po HTTP, ogranicz dostęp — wymagaj tokena autoryzacyjnego albo użyj gniazd domeny uniksowej lub innego mechanizmu IPC z ograniczonym dostępem.
Zasady dla samego transportu HTTP są w specyfikacji sformułowane wprost: serwer musi walidować nagłówek Origin na wszystkich przychodzących połączeniach, a przy obecnym i nieprawidłowym Origin odpowiedzieć kodem 403; uruchamiany lokalnie powinien nasłuchiwać tylko na 127.0.0.1, a nie na 0.0.0.0; i powinien mieć poprawne uwierzytelnianie wszystkich połączeń. Bez tego — cytując specyfikację — atakujący mogą użyć DNS rebindingu, żeby ze zdalnej strony rozmawiać z lokalnym serwerem MCP.
Serwer zdalny aktualizujesz w jednym miejscu i kontrolujesz, co widzi, ale musisz go utrzymać, uwierzytelnić i pilnować, bo stoi w sieci. To jest realny koszt stały, a nie jednorazowy — wróć do niego, zanim obiecasz komuś zdalny serwer.
Opisy narzędzi: to one są produktem, nie kod
Model wybiera narzędzie na podstawie nazwy, opisu i schematu wejścia, więc te trzy pola decydują o trafności wywołań bardziej niż sam kod.
Skoro to model wybiera narzędzie, opis narzędzia jest interfejsem użytkownika tego serwera. Dokumentacja architektury podaje wprost wzorzec nazewnictwa: nazwa ma jednoznacznie identyfikować narzędzie w przestrzeni serwera i trzymać się czytelnego schematu — calculator_arithmetic zamiast samego calculate. Specyfikacja dokłada zalecenia (na poziomie „powinien”): od jednego do stu dwudziestu ośmiu znaków, wielkość liter ma znaczenie, tylko litery ASCII, cyfry, podkreślenie, myślnik i kropka, bez spacji i przecinków, nazwy unikalne w obrębie serwera.
Pole description opisuje, co narzędzie robi i kiedy go użyć — tak formułuje to specyfikacja. Pisz je jak instrukcję dla nowego pracownika, a nie jak komentarz w kodzie: co robi, kiedy sięgnąć, kiedy nie sięgać, co znaczą parametry i w jakim formacie. Osobne pole title służy do wyświetlania człowiekowi, więc możesz mieć jednocześnie techniczną nazwę i ludzką etykietę.
Trzy rzeczy, które podnoszą jakość działania serwera, a które łatwo przeoczyć. Po pierwsze, kolejność: specyfikacja zaleca zwracanie narzędzi w kolejności deterministycznej, bo to pozwala klientom niezawodnie buforować listę i poprawia trafienia w pamięć podręczną promptów modelu. Po drugie, buforowanie: odpowiedzi tools/list niosą pola ttlMs i cacheScope, czyli podpowiedź świeżości i zakres ponownego użycia — warto je ustawiać świadomie, zamiast zostawiać domyślne. Po trzecie, stronicowanie: tools/list obsługuje kursor, więc długa lista nie musi lecieć w jednym kawałku.
Ważny niuans dotyczący uprawnień. Specyfikacja mówi, że zbiór narzędzi nie może zmieniać się „per połączenie” ani jako efekt uboczny innych żądań, ale może zależeć od autoryzacji przedstawionej w danym żądaniu — bo poświadczenia są wejściem żądania, a nie stanem połączenia. To jest sankcjonowany sposób na to, żeby operacje zapisu w ogóle nie pojawiały się na liście komuś, kto nie ma do nich prawa.
Wreszcie błędy. Specyfikacja rozdziela dwie ścieżki: błędy protokołu (nieznane narzędzie, źle zbudowane żądanie) wracają jako zwykłe błędy JSON-RPC, a błędy wykonania narzędzia — awaria API, zła data, wartość poza zakresem, reguła biznesowa — wracają w wyniku z isError: true i treścią, na podstawie której model może się poprawić i spróbować jeszcze raz. Klienty powinny podawać modelowi tę drugą kategorię. Jeśli wszystkie Twoje błędy lecą jako błędy protokołu, odbierasz modelowi możliwość naprawienia własnej pomyłki.
Bezpieczeństwo: lista dozwolonych operacji, limity, dziennik
Specyfikacja nakłada tu na serwer konkretne obowiązki: walidację wejścia, kontrolę dostępu, limity wywołań i sanityzację wyników. Poniżej każdy z nich przełożony na praktykę.
Serwer MCP to wykonywanie kodu na czyjeś żądanie, gdzie „ktoś” to model interpretujący zdanie po polsku. Specyfikacja nakłada na serwery cztery twarde obowiązki przy narzędziach: walidować wszystkie wejścia, wdrożyć właściwą kontrolę dostępu, ograniczać częstotliwość wywołań i sanityzować wyjścia. Po stronie klienta zaleca potwierdzanie operacji wrażliwych przez użytkownika, pokazywanie mu wejść przed wywołaniem — wprost po to, by uniknąć złośliwego lub przypadkowego wycieku danych — walidowanie wyników przed podaniem ich modelowi, limity czasu i logowanie wywołań do celów audytowych.
Do tego dochodzi zasada powtarzana w kilku miejscach: przy narzędziach powinien zawsze istnieć człowiek w pętli, mający możliwość odmówić wywołania. Adnotacje opisujące zachowanie narzędzia klient ma traktować jako niezaufane, jeśli nie pochodzą z zaufanego serwera. To nie jest ozdobnik — adnotacja „to narzędzie tylko czyta” jest deklaracją serwera, a nie gwarancją protokołu.
Osobny wektor ataku wynika wprost z bezstanowości i ma w dokumentacji własną nazwę: przejęcie uchwytu stanu. Skoro serwery pamiętające coś między wywołaniami zwracają jawny uchwyt (identyfikator koszyka, przepływu pracy, sesji roboczej), atakujący, który go zgadnie lub zdobędzie, może operować na cudzym stanie. Wymogi są jednoznaczne: serwer implementujący autoryzację musi weryfikować wszystkie przychodzące żądania i nie może traktować posiadania uchwytu jako uwierzytelnienia. Zalecenia: uchwyty losowe i nieprzewidywalne, wiązane po stronie serwera z uwierzytelnionym użytkownikiem — na przykład przez klucz <user_id>:<uchwyt>, gdzie identyfikator użytkownika pochodzi ze zweryfikowanego tokena, a nie od klienta — oraz odrzucanie uchwytu przedstawionego przez kogokolwiek innego.
- Lista dozwolonych operacjiNie wystawiaj „narzędzia do wykonywania SQL-a”. Wystaw nazwane operacje o określonym kształcie wejścia. Każda dodatkowa swoboda w schemacie to swoboda, którą model wcześniej czy później wykorzysta inaczej, niż zakładałeś.
- Rozdzielenie odczytu od zapisuPierwsza wersja serwera powinna umieć tylko czytać. Zapis to osobna decyzja, osobne poświadczenia i osobne potwierdzenie użytkownika. Dokumentacja bezpieczeństwa opisuje to jako progresywny model najmniejszych uprawnień: minimalny zestaw na start (przykład z dokumentacji to
mcp:tools-basicz operacjami odkrywania i odczytu), podnoszenie zakresu dopiero wtedy, gdy operacja faktycznie go wymaga. - Limity wywołańOgraniczanie liczby wywołań narzędzi jest w specyfikacji obowiązkiem serwera, nie sugestią. Model potrafi wywołać narzędzie w pętli, a każde wywołanie kosztuje u Ciebie zapytanie do bazy albo wywołanie płatnego API.
- Dziennik wywołańZapisuj, co zostało wywołane, z jakimi argumentami, przez kogo i z jakim skutkiem — specyfikacja wymienia logowanie użycia narzędzi do celów audytowych wprost. Bez tego nie odtworzysz żadnego incydentu, a przy narzędziach sterowanych przez model incydent wygląda inaczej niż zwykły błąd aplikacji.
- Zakres uprawnień bez worków zbiorczychDokumentacja wymienia typowe błędy: publikowanie wszystkich możliwych zakresów w
scopes_supported, zakresy typu*,all,full-access, wiązanie niepowiązanych uprawnień „na zapas” i traktowanie zakresu w tokenie jako wystarczającego bez własnej logiki autoryzacji po stronie serwera. - Deterministyczna lista narzędziSpecyfikacja zaleca zwracanie narzędzi w stałej kolejności, bo to poprawia trafność pamięci podręcznej po stronie klienta i modelu. Zbiór narzędzi może natomiast zależeć od autoryzacji przedstawionej w danym żądaniu — i to jest sankcjonowany sposób na ukrycie operacji zapisu przed kimś, kto nie ma do nich prawa.
- Jeśli pośredniczysz do cudzego APIDokumentacja bezpieczeństwa opisuje osobno ryzyko SSRF: klient MCP pobiera adresy z metadanych OAuth, które może kontrolować złośliwy serwer, więc adresy do wewnętrznych zakresów IP, do adresów metadanych chmury i do localhostu powinny być blokowane, a przekierowania walidowane tak samo jak adres pierwotny. Jeśli Twój serwer sam pobiera adresy z zewnątrz, obowiązuje Cię ta sama ostrożność.
Uwierzytelnianie: OAuth 2.1 i zakaz przekazywania tokenów
Autoryzacja w MCP jest opcjonalna, ale przy serwerze zdalnym trudno się bez niej obejść — a jak już ją włączysz, jedna reguła jest bezwzględna.
Specyfikacja mówi to wprost: autoryzacja jest opcjonalna, implementacje na transporcie HTTP powinny się do niej stosować, implementacje na stdio nie powinny i mają brać poświadczenia ze środowiska, a implementacje na innych transportach muszą trzymać się uznanych praktyk bezpieczeństwa swojego protokołu. Gdy już ją włączasz, standard opiera się na OAuth 2.1 i dokłada wymogi, które w praktyce decydują o tym, czy serwer jest bezpieczny.
Serwer MCP występuje jako OAuth-owy resource server i musi zaimplementować OAuth 2.0 Protected Resource Metadata (RFC 9728), żeby klient wiedział, gdzie szukać serwera autoryzacji. Klient musi implementować Resource Indicators (RFC 8707) i wysyłać parametr resource wskazujący konkretny serwer MCP — zarówno w żądaniu autoryzacji, jak i przy wymianie na token — i to niezależnie od tego, czy serwer autoryzacji ten parametr wspiera. Warto też zapamiętać dwie rzeczy z listy wymogów: token idzie w nagłówku Authorization: Bearer, a nie w query stringu, i musi być dołączany do każdego żądania HTTP, bo połączenie nie niesie stanu.
Najważniejsze zdanie całej tej sekcji dotyczy przekazywania tokenów dalej. Dokumentacja bezpieczeństwa nazywa to antywzorcem i formułuje wymóg bez miejsca na interpretację: serwer MCP nie może przyjmować żadnych tokenów, które nie zostały wydane wprost dla niego. Specyfikacja dopowiada, że serwer musi zweryfikować, iż to on jest zamierzonym odbiorcą tokena, może akceptować wyłącznie tokeny ważne dla własnych zasobów i nie może przyjmować ani przekazywać dalej żadnych innych. Powody są wyliczone: przyjmowanie cudzych tokenów rozbraja limity i kontrolę ruchu, psuje ślad audytowy (serwer przestaje odróżniać klientów, a logi API producenta pokazują cudzą tożsamość) i pozwala komuś z wykradzionym tokenem użyć Twojego serwera jako serwera proxy do wyciągania danych.
Jeśli Twój serwer pośredniczy do API trzeciej strony, przeczytaj rozdział o problemie zdezorientowanego zastępcy. Wymogi są konkretne: własny ekran zgody wyświetlany przed przekierowaniem do zewnętrznego serwera autoryzacji, rejestr zatwierdzonych client_id per użytkownik sprawdzany przed rozpoczęciem przepływu, dokładne (a nie wzorcowe) dopasowanie redirect_uri, ochrona przed CSRF i przed osadzeniem ekranu zgody w ramce, oraz jednorazowy, krótko żyjący parametr state — którego ciasteczko lub sesję ustawiasz dopiero po zatwierdzeniu zgody przez użytkownika. Ostatni punkt jest kluczowy: ustawienie go wcześniej sprawia, że ekran zgody przestaje cokolwiek chronić.
Rozszerzenia: co jest poza rdzeniem protokołu
Długie zadania w tle, interfejs wewnątrz rozmowy i uwierzytelnianie maszyna–maszyna nie należą do rdzenia MCP. To opcjonalne rozszerzenia, które obie strony muszą jawnie włączyć.
Poza rdzeniem specyfikacja definiuje rozszerzenia: dodatki modularne, wyspecjalizowane albo eksperymentalne. Dokumentacja stawia przy nich trzy warunki, które ułatwiają planowanie. Są zawsze domyślnie wyłączone i wymagają jawnego włączenia przez programistę. Są negocjowane — klient deklaruje obsługę w polu extensions wewnątrz io.modelcontextprotocol/clientCapabilities, serwer w odpowiedzi server/discover. I ewoluują niezależnie od rdzenia.
Strona rozszerzeń wymienia kilka oficjalnych rodzin. Tasks obsługuje długie operacje asynchronicznie: klient odpytuje o status, serwer może w trakcie poprosić o dane, a zadanie ma trwały uchwyt. Jeśli Twoje narzędzie pracuje minutami, zajrzyj tu, zamiast przeciągać jedno wywołanie. MCP Apps pozwala serwerowi pokazać w rozmowie interaktywne elementy: wykresy, formularze, odtwarzacze wideo. Skills over MCP udostępnia instrukcje do przepływów pracy i pliki pomocnicze przez zasoby MCP. Osobna rodzina dotyczy autoryzacji: przepływ OAuth client credentials do połączeń maszyna–maszyna i autoryzacja zarządzana centralnie przez firmę.
Praktyczna konsekwencja przy wyborze SDK: dokumentacja tierów mówi tylko tyle, że funkcje eksperymentalne i rozszerzenia protokołu nie są wymagane w żadnym tierze, a zdanie o pełnej autonomii maintainerów SDK co do obsługiwanych rozszerzeń stoi na osobnej stronie o rozszerzeniach. Jeśli budujesz na Tasks albo Apps, sprawdź to w dokumentacji konkretnego SDK, bo sam tier nic tu nie obiecuje.
Dobra praktyka, którą dokumentacja nazywa łagodną degradacją: jeśli jedna strona obsługuje rozszerzenie, a druga nie, obsługująca ma albo wrócić do zachowania rdzenia, albo odrzucić żądanie z czytelnym błędem, gdy rozszerzenie jest obowiązkowe. Serwer z narzędziami wzbogaconymi o interfejs powinien nadal zwracać sensowną treść tekstową klientom bez tego rozszerzenia.
Wersje protokołu i co to znaczy dla utrzymania
Numer wersji protokołu zmienia się tylko przy zmianach łamiących zgodność, a funkcje przestarzałe zostają w specyfikacji co najmniej 90 dni albo 12 miesięcy. Te terminy wyznaczają rytm aktualizacji Twojego serwera.
Wersje protokołu są datami w formacie RRRR-MM-DD i — jak zaznacza dokumentacja — numer nie rośnie przy każdej aktualizacji, a wyłącznie wtedy, gdy zmiana łamie zgodność wstecz. Obowiązująca wersja to 2026-07-28; adres /specification/latest przekierowuje właśnie na nią. Negocjacja jest per żądanie: klient deklaruje wersję w polu _meta, a na Streamable HTTP dodatkowo w nagłówku MCP-Protocol-Version, którego wartość musi zgadzać się z ciałem żądania — w przeciwnym razie serwer odrzuca żądanie kodem 400 i błędem HeaderMismatch. Przy nieobsługiwanej wersji serwer odpowiada błędem UnsupportedProtocolVersionError z listą wersji, które obsługuje. Klient i serwer mogą obsługiwać wiele wersji naraz.
Funkcje usuwane ze standardu przechodzą najpierw przez status „przestarzała”. Strona o wersjonowaniu podaje termin z wyjątkiem, którego łatwo nie zauważyć: taka funkcja zostaje w specyfikacji co najmniej dwanaście miesięcy — albo co najmniej dziewięćdziesiąt dni, jeśli zadziała przewidziany w polityce cyklu życia wyjątek przyspieszonego usunięcia. Planuj według krótszego terminu, nie dłuższego. Aktualnie przestarzałe funkcje są wypisane w osobnym rejestrze, do którego ta strona linkuje — warto go raz na kwartał przejrzeć.
Praktyczny wniosek: nie wpisuj wersji protokołu na sztywno w logikę biznesową. Trzymaj ją w SDK, a SDK aktualizuj świadomie — repozytoria publikują tabele zgodności wersji biblioteki z wersjami specyfikacji, jak robi to SDK dla Go. Do tego dochodzi drugi sygnał, który warto obserwować: tier SDK jest mierzony testami zgodności i może zostać obniżony, jeśli testy padają nieprzerwanie przez cztery tygodnie albo zgłoszenia leżą dwa miesiące bez reakcji.
Jeśli Twój serwer ma współpracować z klientami sprzed wersji 2026-07-28, weź pod uwagę, że tamte wersje wymagały uścisku dłoni initialize, pozwalały serwerowi wysyłać własne żądania JSON-RPC na strumieniach SSE i znały sesje na poziomie protokołu z nagłówkiem Mcp-Session-Id oraz wznawianie strumieni przez Last-Event-ID. Specyfikacja opisuje, jak wykryć, z którą epoką rozmawiasz — klient sonduje żądaniem server/discover i dopiero przy nierozpoznanym błędzie schodzi do initialize — ale to jest kod, który trzeba napisać i przetestować. Decyzja o wstecznej zgodności nie jest darmowa i warto ją podjąć świadomie, a nie przy okazji.
Pytania i odpowiedzi
Serwer MCP — co to właściwie jest, w jednym zdaniu?
To program, który wystawia aplikacji AI zestaw nazwanych narzędzi, danych i szablonów, opisanych na tyle dokładnie, żeby model mógł sam zdecydować, którego użyć. Komunikacja idzie po JSON-RPC 2.0, przez standardowe strumienie procesu (stdio) albo przez jedną ścieżkę HTTP przyjmującą POST.
TypeScript, .NET czy coś innego — w czym pisać?
W tym, w czym stoi reszta Twojego systemu. Oficjalnych SDK jest dziesięć; w tierze 1, czyli ze stuprocentową zgodnością testową i nowymi funkcjami protokołu przed wydaniem nowej wersji specyfikacji, są TypeScript, Python, C#, Go, Rust i Ruby. Java jest w tierze 2, a Swift, PHP i Kotlin w tierze 3. Serwer MCP to cienka warstwa nad Twoim istniejącym kodem — zmiana języka tylko po to, żeby użyć modnej biblioteki, oznacza drugi kod do utrzymania i te same narzędzia na końcu.
Czy mogę uruchomić serwer MCP lokalnie, bez wystawiania go do internetu?
Tak i to jest zalecany start. Serwer lokalny działa na transporcie stdio: host uruchamia go jako proces potomny i rozmawia przez standardowe strumienie. Nie potrzebujesz hostingu ani OAuth-a — specyfikacja autoryzacji mówi, że implementacje na stdio nie powinny jej stosować i mają pobierać poświadczenia ze środowiska. Jeśli mimo to wystawiasz serwer lokalny po HTTP, ma walidować nagłówek Origin (403 przy nieprawidłowym) i nasłuchiwać tylko na 127.0.0.1.
Dlaczego mój serwer na stdio się nie uruchamia?
Pierwsze, co sprawdź: czy cokolwiek w Twoim procesie pisze na stdout. Specyfikacja zabrania wypisywania tam czegokolwiek, co nie jest poprawną wiadomością MCP, a dokumentacja ostrzega przy każdym języku osobno: print() w Pythonie, console.log() w Node, System.out.println() w Javie, println() w Kotlinie i Console.WriteLine() w C# domyślnie piszą właśnie tam i psują strumień JSON-RPC. Przenieś logi na stderr — specyfikacja wprost na to pozwala. Przy serwerze HTTP ten problem nie występuje: tam logowanie na standardowe wyjście jest w porządku.
Czy muszę robić OAuth, jeśli wystawiam serwer po HTTP?
Nie z automatu. Specyfikacja mówi, że autoryzacja jest w MCP opcjonalna, a dokumentacja architektury wymienia dla Streamable HTTP standardowe metody uwierzytelniania HTTP — tokeny bearer, klucze API i własne nagłówki — rekomendując OAuth jako sposób zdobycia tokena. Jeśli jednak wdrażasz autoryzację na transporcie HTTP, specyfikacja zaleca oprzeć ją na OAuth 2.1 — wtedy serwer implementuje RFC 9728, klient wysyła parametr resource z RFC 8707, a serwer musi zweryfikować, że token został wydany właśnie dla niego.
Czym to się różni od zwykłego API, które już mam?
Tym, kto decyduje o wywołaniu. W Twoim API decyduje kod, który sam napisałeś, i zna kolejność kroków. W MCP decyduje model, na podstawie opisów publikowanych przez serwer. Dlatego opis narzędzia i schemat wejścia przestają być dokumentacją, a stają się mechanizmem kontroli — a każde narzędzie musi być bezpieczne niezależnie od tego, czy model wywołał je jako pierwsze, czy jako trzecie.
Ile narzędzi powinien mieć pierwszy serwer?
Trzy i wszystkie wyłącznie do odczytu. Trzy wystarczą, żeby sprawdzić, czy model trafnie wybiera narzędzie na podstawie opisu, a brak zapisu oznacza, że najgorszy możliwy błąd to zła odpowiedź, a nie zmiana w Twoich danych. Zapis, transport HTTP i uwierzytelnianie dokładaj jako osobne, świadome decyzje.
Jak serwer ma pamiętać cokolwiek między wywołaniami, skoro protokół jest bezstanowy?
Przez jawny uchwyt. Narzędzie tworzące zwraca identyfikator (koszyka, transakcji, sesji roboczej), a kolejne wywołania przyjmują go jako zwykły argument — protokół nie zna pojęcia uchwytu, to po prostu ciąg znaków w wyniku i w argumentach. Warunki są jednak twarde: serwer nie może traktować posiadania uchwytu jako uwierzytelnienia, uchwyty mają być losowe i nieprzewidywalne, a stan wiązany po stronie serwera z uwierzytelnionym użytkownikiem. Dokumentacja radzi też podać czas życia uchwytu w opisie narzędzia i zwracać czytelny błąd, gdy uchwyt wygasł.
Źródła
Liczby i terminy w tym przewodniku sprawdziłem w oficjalnych źródłach. Ceny i przepisy się zmieniają, więc przy decyzji warto zajrzeć do nich ponownie.
- Model Context Protocol — czym jest MCP (dokumentacja oficjalna)
- Specyfikacja MCP 2026-07-28 — przegląd, funkcje, zasady bezpieczeństwa
- MCP — architektura: role, warstwy, bezstanowość, uwierzytelnianie na transporcie
- MCP — narzędzia, zasoby, prompty i kto nimi steruje
- Specyfikacja MCP — narzędzia: schematy, nazwy, błędy, wymogi bezpieczeństwa
- Specyfikacja MCP — transport stdio (stdout, stderr, restart)
- Specyfikacja MCP — transport Streamable HTTP (Origin, localhost, nagłówki)
- Specyfikacja MCP — autoryzacja: opcjonalność, OAuth 2.1, RFC 9728, RFC 8707
- MCP — dobre praktyki bezpieczeństwa (token passthrough, uchwyty stanu, serwery lokalne, SSRF)
- MCP — lista oficjalnych SDK i ich tiery
- MCP — system tierów SDK (wymagania, zobowiązania, degradacja)
- MCP — wersjonowanie protokołu, negocjacja i polityka wycofywania funkcji
- Specyfikacja MCP 2026-07-28 — rejestr przestarzałych funkcji (sampling, roots, logging, terminy usunięcia)
- MCP — macierz obsługi rozszerzeń przez klientów
- MCP Inspector — epoki protokołu (legacy jako tryb domyślny, modern dla 2026-07-28)
- MCP — przewodnik: zbuduj własny serwer (logowanie, instalacja SDK)
- MCP — rozszerzenia protokołu: Tasks, MCP Apps, Skills, rozszerzenia autoryzacji
- MCP TypeScript SDK (pakiety v2, wsparcie dla v1.x)
- MCP Python SDK (linia v2, przewodnik migracji)
- PyPI: pakiet mcp (wydania linii 2.x, status stabilny)
- MCP Python SDK — co nowego w v2 (obsługa 2026-07-28, utrzymanie v1.x)
- MCP C# SDK (pakiety NuGet, współpraca z Microsoftem)
- MCP Go SDK (współpraca z Google, tabela zgodności wersji)
- MCP Rust SDK — crate rmcp (tokio, zgodność ze specyfikacją)
- MCP Java SDK (Maven Central, Java 17+, integracja ze Spring AI)
- MCP Ruby SDK (gem mcp, stdio i Streamable HTTP, integracja z Rails)
- MCP Ruby SDK — obsługiwane wersje protokołu (dokumentacja gema 1.7.0)
- MCP Kotlin SDK (Kotlin Multiplatform: JVM, Native, JS, Wasm)
- MCP PHP SDK (współpraca Fundacji PHP i Symfony, status eksperymentalny)
- MCP Swift SDK (deklarowana wersja specyfikacji w README)
- MCP Registry — oficjalny rejestr serwerów (wersja zapoznawcza)
- MCP — referencyjne implementacje serwerów
- MCP Inspector — oficjalne narzędzie do testowania serwerów
Masz pytanie do swojego projektu?
Opisz, co chcesz osiągnąć. Odpowiem konkretnie, także wtedy, gdy najlepszą odpowiedzią jest „nie rób tego”.
Jonasz Jankowski · Bezpośrednia współpraca · Mikołów (Śląsk), zdalnie w całej Polsce
- Odpowiadam osobiście w ciągu jednego dnia roboczego.
- Krótka rozmowa o celu, funkcjach, materiałach i integracjach.
- Dostajesz zakres z etapami i konkretną kwotę, zanim cokolwiek zaczniemy.