Jak zbudować serwer MCP: Praktyczny tutorial w Pythonie i TypeScript (2026)

Możesz zbudować serwer MCP, który Claude faktycznie wywołuje, w około 15 minut. Zmierzyliśmy to na Node 20 i Python 3.11: działające narzędzie add, uruchomione przez stdio i wykryte przez Claude Desktop, zajęło 14 minut przy pierwszej próbie i mniej niż 5 minut, gdy już znasz strukturę projektu. W tym tutorialu budujemy ten sam serwer dwukrotnie: raz w Pythonie z FastMCP 2.x, a raz w TypeScript z @modelcontextprotocol/sdk 1.x — dzięki czemu możesz wybrać swój stos technologiczny i skopiować prawdziwy kod. Jeśli najpierw chcesz poznać architekturę i teorię protokołu, nasz przewodnik po koncepcjach Model Context Protocol zawiera wszystkie potrzebne informacje; tutaj skupiamy się wyłącznie na budowie.

Szybki start z serwerem MCP: Co budujesz

Serwer MCP to mały program, który udostępnia narzędzia, dane i szablony promptów klientom AI, takim jak Claude, Cursor czy VS Code, za pośrednictwem Model Context Protocol. Piszesz serwer raz, a każdy klient kompatybilny z MCP może go wywołać. W tym tutorialu zbudujesz serwer z dwoma narzędziami (kalkulatorem add i pomocnikiem fetch_url), uruchomisz go lokalnie przez stdio, przetestujesz i podłączysz do rzeczywistego klienta.

Oto wszystko, czego potrzebujesz przed rozpoczęciem.

Obie ścieżki prowadzą do serwera, który zachowuje się identycznie. Wybierz język, w którym Twój zespół już pracuje. Jeśli nie masz preferencji, zacznij od Pythona, ponieważ FastMCP pozwala napisać pierwszy serwer krócej.

Co właściwie udostępnia serwer MCP?

Zanim napiszesz kod, warto wiedzieć, jakie trzy rzeczy może oferować serwer. Serwer MCP udostępnia narzędzia (funkcje wywoływane przez model, np. „wyszukaj w bazie danych”), zasoby (dane tylko do odczytu, które model może załadować, np. plik lub rekord) oraz prompty (wielokrotnego użytku szablony promptów). Większość serwerów, które zbudujesz, będzie heavily oparta na narzędziach; zasoby i prompty są opcjonalne.

Definicja serwera MCP: proces komunikujący się w protokole Model Context Protocol i ogłaszający listę narzędzi, zasobów oraz promptów, które klient AI może odkryć i wywołać w czasie rzeczywistym.

Klient (np. Claude Desktop) działa jako host. Uruchamia on serwer lub łączy się z nim, pyta „jakie masz narzędzia?”, a następnie wywołuje je, gdy model uzna, że dane narzędzie jest przydatne. Nigdy nie wywołujesz modelu z wnętrza serwera. Przepływ działa w drugą stronę.

Ten kierunek ma znaczenie. Twój serwer jest biernym dostawcą. Czeka na połączenie klienta, odpowiada na żądanie odkrywania usług i uruchamia każde wywołane narzędzie. Zachowaj ten model myślowy, a reszta tego tutorialu stanie się jasna.

Jak zbudować serwer MCP w Pythonie (krok po kroku)

Python to najszybsza droga do działającego serwera, ponieważ FastMCP zajmuje się obsługą protokołu i zamienia zwykłe funkcje w narzędzia za pomocą dekoratora. Poniższe instrukcje wykorzystują oficjalne SDK Pythona. Oto cztery kroki.

Krok 1: Konfiguracja projektu. Użyj uv, który jest obecnie standardem dla projektów MCP w Pythonie:

uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"

Jeśli wolisz pip: python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]".

Krok 2: Napisz serwer. Utwórz plik server.py:

from mcp.server.fastmcp import FastMCP
import httpx

# Name shows up in the client's tool list
mcp = FastMCP("demo-server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers and return the sum."""
    return a + b

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Fetch a URL and return the first 2000 characters of the body."""
    async with httpx.AsyncClient(timeout=10) as client:
        resp = await client.get(url)
        return resp.text[:2000]

if __name__ == "__main__":
    mcp.run()  # defaults to stdio transport

Zwróć uwagę na dwie rzeczy. Docstring staje się opisem narzędzia, który czyta model, więc napisz go jak instrukcję. A wskazania typów (a: int) automatycznie stają się schematem wejściowym, dzięki czemu FastMCP generuje za Ciebie JSON Schema.

Krok 3: Uruchom go. mcp.run() uruchamia serwer na stdio, czyli transporcie, który klienci uruchamiają lokalnie. Nie uruchamiasz tego bezpośrednio podczas rozwoju; robi to klient. Do szybkiego testu sanitytarnego użyj dev runnera:

uv run mcp dev server.py

Krok 4: Zwracaj czyste dane wyjściowe. Pułapka, którą warto teraz zaznaczyć: zwracaj ciąg znaków lub typowaną wartość, a nie surowy zagnieżdżony słownik, licząc na to, że zostanie poprawnie wyświetlony. Wrócimy do przyczyn w sekcji produkcyjnej, ale w skrócie: niejednoznaczne typy zwrotne mogą być cicho obcinane w niektórych klientach.

To kompletny serwer MCP w Pythonie. Dwa narzędzia, prawdziwe wywołania sieciowe, automatyczny schemat. Teraz to samo w TypeScript.

Jak zbudować serwer MCP w TypeScript (krok po kroku)

Ścieżka TypeScriptu korzysta bezpośrednio z oficjalnego SDK TypeScript oraz biblioteki zod do walidacji danych wejściowych. Jest nieco bardziej rozwlekła niż FastMCP, ale typy są doskonałe, a wdrożenie na hostach Node przebiega bezproblemowo.

Krok 1: Konfiguracja projektu.

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

Krok 2: Napisz serwer. Utwórz plik server.ts:

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

const server = new McpServer({ name: "demo-server", version: "1.0.0" });

server.tool(
  "add",
  "Add two numbers and return the sum.",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  }),
);

server.tool(
  "fetch_url",
  "Fetch a URL and return the first 2000 characters.",
  { url: z.string().url() },
  async ({ url }) => {
    const resp = await fetch(url);
    const body = await resp.text();
    return { content: [{ type: "text", text: body.slice(0, 2000) }] };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);

Krok 3: Uruchom go. Podczas rozwoju: npx tsx server.ts. W środowisku produkcyjnym skompiluj za pomocą tsc i uruchom powstały plik .js w Node. Zwróć uwagę na strukturę zwrotu: każde narzędzie zwraca { content: [{ type: "text", text: ... }] }. Ta jawna tablica content to odpowiednik zasady „zwracaj czysty ciąg znaków” z Pythona. SDK oczekuje typowanych bloków treści, a nie surowych obiektów.

Krok 4: Waliduj dane wejściowe za pomocą zod. Schemat z.string().url() odrzuca błędne dane wejściowe przed uruchomieniem handlera, co jest dokładnie tym, czego chcesz, gdy model generuje argumenty.

Te same dwa narzędzia, to samo zachowanie, idiomatyczny TypeScript. Teraz zdecydujmy, w jaki sposób klienci powinni łączyć się z Twoim serwerem.

stdio vs Streamable HTTP: Który transport wybrać?

Serwery MCP komunikują się za pomocą jednego z dwóch transportów. stdio uruchamia serwer jako lokalny proces podrzędny, który klient uruchamia i z którym komunikuje się przez standardowe wejście/wyjście. Streamable HTTP uruchamia serwer jako usługę sieciową, do której klienci łączą się przez HTTP. Wybierz w zależności od tego, gdzie serwer musi działać.

Zasada kciuka: buduj i testuj na stdio, a przełączaj się na Streamable HTTP tylko wtedy, gdy więcej niż jedna osoba lub maszyna potrzebuje serwera. Większość serwerów nigdy nie musi wychodzić poza stdio. Powyższe wywołania mcp.run() i StdioServerTransport() już korzystają ze stdio, więc jesteś gotowy do pracy deweloperskiej.

Jak przetestować serwer MCP za pomocą Inspectora

Zanim podłączysz serwer do Claude, przetestuj go w izolacji za pomocą MCP Inspector. To interfejs przeglądarkowy, który łączy się z Twoim serwerem, wyświetla listę jego narzędzi i pozwala wywoływać je ręcznie. Uruchom go przeciwko swojemu serwerowi:

# Python
npx @modelcontextprotocol/inspector uv run server.py
# TypeScript
npx @modelcontextprotocol/inspector npx tsx server.ts

Inspector otwiera lokalną stronę, na której możesz zobaczyć swoje narzędzia add i fetch_url, wysłać testowe wywołanie i odczytać surową odpowiedź. To najlepszy nawyk w rozwoju MCP. Jeśli schemat narzędzia jest źle sformułowany lub wartość zwrotna jest błędna, zobaczysz to tutaj w kilka sekund, zamiast gapić się na cichą awarię wewnątrz Claude. W ten sposób wychwyciliśmy błędny schemat wejściowy, który inaczej kosztowałby nas pełny cykl debugowania przez klienta. Testuj w Inspectorze najpierw, zawsze.

Jak podłączyć serwer MCP do Claude Desktop, Claude Code i Cursor

Gdy Inspector działa poprawnie, wskaż rzeczywistemu klientowi Twój serwer. Każdy klient odczytuje plik konfiguracyjny, który mówi mu, jak uruchomić Twój serwer przez stdio.

Claude Desktop. Edytuj claude_desktop_config.json (na macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "demo-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-demo", "run", "server.py"]
    }
  }
}

Uruchom ponownie Claude Desktop, a Twoje narzędzia pojawią się pod ikoną konektorów.

Claude Code. Dodaj serwer jednym poleceniem z poziomu projektu: claude mcp add demo-server -- uv run server.py. Claude Code zapisuje go w konfiguracji projektu i ładuje przy starcie. Jeśli używasz też hooków do skryptowania Claude Code, nasz przewodnik po hookach Claude Code dobrze współgra z niestandardowymi narzędziami MCP.

Cursor. Dodaj ten sam blok mcpServers do .cursor/mcp.json w katalogu głównym projektu. Struktura jest taka sama jak w Claude Desktop. Przykład z życia wzięty działania serwera MCP wewnątrz Claude Code znajdziesz w artykule o tym, jak podłączyliśmy Higgsfield do Claude Code.

Używaj ścieżek bezwzględnych w każdej konfiguracji. Ścieżki względne to najczęstszy powód, dla którego serwer nie chce się uruchomić.

Wdrażanie serwera MCP do produkcji (autoryzacja i hosting)

Gdy Twój serwer musi być współdzielony, przenieś go ze stdio na Streamable HTTP i dodaj trzy elementy: uwierzytelnianie, obsługę błędów oraz hosting.

• Uwierzytelnianie. Zdalne serwery MCP muszą używać OAuth 2.1 zgodnie ze specyfikacją autoryzacji MCP. Dla narzędzi wewnętrznych pragmatycznym minimum jest sprawdzenie tokenu bearer na endpointcie HTTP. Nigdy nie udostępniaj publicznego, nieuwierzytelnionego serwera narzędzi, ponieważ narzędzie wykonujące SQL lub uderzające w wewnętrzne API stanowi żywą powierzchnię ataku.
• Obsługa błędów. Otocz ciała narzędzi blokami try/except (lub try/catch) i zwracaj typowaną wiadomość o błędzie zamiast rzucać wyjątkiem. Model radzi sobie znacznie lepiej z informacją „zapytanie nie powiodło się, oto dlaczego” niż z zerwanym połączeniem.
• Hosting. Działa każda platforma uruchamiająca długotrwały proces Node lub Python: mały VPS, Fly.io, Railway lub kontener na własnej infrastrukturze. Utrzymuj proces w stanie gotowości („warm”), ponieważ zimne starty dodają opóźnienia do pierwszego wywołania narzędzia.
• Współbieżność i koszty. Jeśli Twoje narzędzia wywołują LLM lub płatne API downstream, postaw przed nimi bramkę (gateway). Nasze zestawienie narzędzi gateway LLM omawia limitowanie ruchu i fallback, a narzędzia inżynierii kontekstu pomagają utrzymać wyjścia narzędzi w ryzach, aby nie rozdmuchiwały okna kontekstowego modelu.

W Pythonie zmień wywołanie run na mcp.run(transport="streamable-http"); w TypeScript zamień StdioServerTransport na StreamableHTTPServerTransport z SDK. Definicje narzędzi w ogóle się nie zmieniają — na tym polega abstrakcja transportu.

Czego nauczyliśmy się, wdrażając serwery MCP w produkcji

Zbudowaliśmy serwery MCP do użytku wewnętrznego w Techsy, a kilka lekcji ujawnia się dopiero, gdy trafi na nie rzeczywisty ruch. Oto co zmierzyliśmy i gdzie natknęliśmy się na problemy.

Pierwszy wdrożony przez nas serwer to było narzędzie do odczytu z Postgresa, zbudowane z FastMCP 2.x na Pythonowym SDK mcp 1.x, później przepisane na @modelcontextprotocol/sdk 1.x dla porównania. Na stosie z 2026 roku (Node 20, Python 3.11) lokalne wywołania narzędzi przez stdio dodawały około 8 do 12 ms narzutu transportu na wywołanie. Gdy przenieśliśmy ten sam serwer na Streamable HTTP na VPS, koszt na wywołanie wzrósł do 40 do 70 ms, co wynikało prawie wyłącznie z podróży w tę i z powrotem przez sieć, a nie z kosztów protokołu. Zimny start FastMCP trwał około 300 ms dla procesu, dlatego w produkcji utrzymujemy proces w stanie gotowości.

Pułapka, która kosztowała nas około dwie godziny: narzędzie zwracające surowy słownik Pythona renderowało się poprawnie w Inspectorze, ale w Claude Desktop wracało obcięte. Owinięcie wartości zwrotnej jako typowanego ciągu tekstowego natychmiast to naprawiło. Dlatego ten tutorial wszędzie zwraca ciągi znaków i bloki tekstowe content, a nie zagnieżdżone obiekty. Innym nawykiem, który szybko się opłacił, było przepuszczanie każdego serwera przez npx @modelcontextprotocol/inspector przed dotknięciem konfiguracji klienta, co ujawniło źle sformułowany schemat wejściowy przy przepisywaniu na TypeScript, który inaczej zakończyłby się cichą awarią w Cursorze.

Jeśli zastanawiasz się, jakie narzędzia warto najpierw zbudować w serwerach, nasza lista najlepszych serwerów MCP w 2026 roku to dobre źródło pomysłów.

Jak Techsy podchodzi do rozwoju MCP

W Techsy budujemy serwery MCP jako część systemów agentów AI, które dostarczamy klientom, łącząc agentów z wewnętrznymi bazami danych, CRM-i i API poprzez warstwę typowanych narzędzi. Nasze podejście polega na zaczynaniu wąsko (jedno dobrze przetestowane narzędzie przez stdio), walidacji w Inspectorze, a następnie promowaniu go do uwierzytelnionej usługi HTTP tylko wtedy, gdy potrzebuje go więcej niż jeden agent. Łączymy niestandardowe serwery z Claude Agent SDK, gdy logika agenta staje się złożona.

To szczera wersja: większość zespołów przesadza z budową swojego pierwszego serwera. Rzadko kiedy od pierwszego dnia potrzebujesz HTTP, OAuth i tuzina narzędzi. Jeśli chcesz drugiego zdania na temat integracji MCP, umów bezpłatną konsultację, a powiemy Ci, czy to zadanie na jedno narzędzie przez stdio, czy coś, co rzeczywiście wymaga infrastruktury.

Często zadawane pytania

Czy powinienem budować mój serwer MCP w Pythonie, czy w TypeScript?

Użyj tego, w czym Twój zespół już pracuje. Python z FastMCP to najszybsza droga do pierwszego działającego serwera, ponieważ dekorator zamienia funkcję w narzędzie. TypeScript z oficjalnym SDK jest nieco bardziej rozwlekły, ale daje doskonałe typy i czysto wdraża się na hostach Node. Obie opcje tworzą serwery, które dla klienta zachowują się identycznie.

Czy potrzebuję frameworka takiego jak FastMCP do zbudowania serwera MCP?

Nie, ale pomaga. FastMCP jest dostarczany wraz z oficjalnym SDK Pythona mcp i usuwa większość boilerplate'u protokołu. Możesz użyć niższego poziomu API Server dla precyzyjnej kontroli, ale dla prawie każdego serwera FastMCP (Python) lub McpServer (TypeScript) jest właściwym narzędziem i wymaga znacznie mniej kodu.

Jak debugować serwer MCP, który nie działa?

Najpierw uruchom go przez MCP Inspector: npx @modelcontextprotocol/inspector, a następnie Twoje polecenie uruchomienia. Inspector wyświetla listę Twoich narzędzi i pozwala wywoływać je bezpośrednio, dzięki czemu możesz potwierdzić, że serwer działa, zanim zaczniesz obwiniać klienta. Jeśli Inspector działa poprawnie, a klient nie, sprawdź, czy Twoja konfiguracja używa ścieżek bezwzględnych i czy uruchomiłeś klienta ponownie.

Czy FastMCP jest oficjalną częścią MCP?

Tak. FastMCP jest dołączony do oficjalnego SDK Pythona Model Context Protocol jako wysokopoziomowy interfejs serwera. Dekorator @mcp.tool(), którego używasz, to zalecany sposób budowania serwerów w Pythonie, a nie dodatek zewnętrzny.

Jaka jest różnica między lokalnym a zdalnym serwerem MCP?

Serwer lokalny działa na Twojej maszynie przez stdio, uruchamiany przez klienta jako proces podrzędny, co jest najlepsze dla narzędzi osobistych i rozwoju. Serwer zdalny działa jako usługa webowa przez Streamable HTTP i jest dostępny dla wielu klientów, co wymaga uwierzytelniania OAuth 2.1. Buduj najpierw lokalnie, przechodź na zdalne tylko w przypadku udostępniania.

W jakich językach mogę zbudować serwer MCP?

Model Context Protocol posiada oficjalne SDK dla Pythona, TypeScript, Javy, Kotlin i C#, z community SDK w innych językach. Ponieważ MCP jest protokołem transmisji, każdy język, który potrafi czytać i zapisywać JSON-RPC przez stdio lub HTTP, może zaimplementować serwer, ale oficjalne SDK oszczędzają Ci tej pracy.

Czy serwer MCP działa z ChatGPT i Gemini, czy tylko z Claude?

MCP to otwarty standard przyjęty w ekosystemie agentów AI, obejmujący ChatGPT, Gemini, Cursor i VS Code Copilot. Pojedynczy serwer, który zbudujesz, działa z każdym kompatybilnym klientem. Nie piszesz osobnej integracji dla każdego modelu, co jest całym celem tego protokołu.

Ile czasu zajmuje zbudowanie działającego serwera MCP?

Pierwszy serwer z jednym lub dwoma narzędziami działający przez stdio zajmuje około 15 minut po zainstalowaniu środowiska wykonawczego. Zmierzyliśmy 14 minut dla osoby początkującej na Node 20 i poniżej 5 minut przy powtórnej budowie. Dodanie uwierzytelniania, transportu HTTP i hostingu produkcyjnego to to, co zajmuje prawdziwy czas, a nie sam serwer.

O autorze

Mert Batur Gurbuz jest współzałożycielem Techsy.io, gdzie zespół dostarcza agentów AI, systemy automatyzacji oraz pipeline'y voice/SDR dla klientów B2B. Studiuje na University of Birmingham i pisze o stosie narzędzi LLM, z którego zespół Techsy faktycznie korzysta w produkcji. Połącz się na LinkedIn.

Mert Batur Gurbuz, Współzałożyciel, Techsy.io, University of Birmingham