Jak vytvořit MCP server: Podrobný návod v Pythonu a TypeScriptu (2026)

Funkční MCP server, který Claude skutečně volá, můžete vytvořit přibližně za 15 minut. Otestovali jsme to na Node 20 a Pythonu 3.11: funkční nástroj add běžící přes stdio, který byl detekován aplikací Claude Desktop, nám poprvé zabral 14 minut a při znalosti struktury méně než 5 minut. Tento návod vytvoří stejný server dvakrát – jednou v Pythonu s FastMCP 2.x a podruhé v TypeScriptu s @modelcontextprotocol/sdk 1.x – abyste si mohli vybrat svůj stack a kopírovat skutečný kód. Pokud chcete nejprve pochopit architekturu a teorii protokolu, náš průvodce koncepty Model Context Protocol vám vše vysvětlí; zde se zaměříme pouze na tvorbu.

Rychlý start s MCP serverem: Co budete vytvářet

MCP server je malý program, který zpřístupňuje nástroje, data a šablony promptů klientům AI, jako jsou Claude, Cursor nebo VS Code, prostřednictvím Model Context Protocol. Server napíšete jednou a jakýkoli klient kompatibilní s MCP ho může volat. V tomto návodu vytvoříte server se dvěma nástroji (kalkulačka add a pomocník fetch_url), spustíte jej lokálně přes stdio, otestujete ho a připojíte ke skutečnému klientovi.

Zde je vše, co potřebujete před začátkem.

Obě cesty vedou k serveru, který se chová identicky. Vyberte jazyk, ve kterém váš tým již vydává software. Pokud nemáte preference, začněte s Pythonem, protože FastMCP umožňuje vytvořit první server stručněji.

Co vlastně MCP server zpřístupňuje?

Než začnete psát kód, je užitečné vědět, jaké tři věci může server nabízet. MCP server zpřístupňuje nástroje (funkce, které model může volat, například „vyhledat v databázi“), zdroje (data pouze pro čtení, která model může načíst, například soubor nebo záznam) a prompty (znovu použitelné šablony promptů). Většina serverů, které vytvoříte, bude silně orientovaná na nástroje; zdroje a prompty jsou volitelné.

Definice MCP serveru: proces, který komunikuje pomocí Model Context Protocol a inzeruje seznam nástrojů, zdrojů a promptů, které klient AI může za běhu objevit a vyvolat.

Klient (například Claude Desktop) funguje jako hostitel. Spustí nebo se připojí k vašemu serveru, zeptá se „jaké máte nástroje?“ a poté je zavolá, když model usoudí, že je nástroj užitečný. Nikdy nevoláte model zevnitř serveru. Tok probíhá opačným směrem.

Tento směr je důležitý. Váš server je pasivním poskytovatelem. Čeká, až se klient připojí, odpoví na žádost o objevování služeb a spustí jakýkoli volaný nástroj. Mějte tento mentální model na paměti a zbytek tohoto návodu do sebe zapadne.

Jak vytvořit MCP server v Pythonu (krok za krokem)

Python je nejrychlejší cestou k běžícímu serveru, protože FastMCP řeší protokolovou infrastrukturu a mění obyčejné funkce na nástroje pomocí dekorátoru. Vše níže využívá oficiální Python SDK. Zde jsou čtyři kroky.

Krok 1: Nastavení projektu. Použijte uv, což je nyní standard pro projekty MCP v Pythonu:

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

Pokud preferujete pip: python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]".

Krok 2: Napsání serveru. Vytvořte 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

Všimněte si dvou věcí. Docstring se stává popisem nástroje, který model čte, takže jej pište jako instrukci. A typové nápovědy (a: int) se automaticky stanou vstupním schématem, takže FastMCP za vás vygeneruje JSON Schema.

Krok 3: Spuštění. mcp.run() spustí server na stdio, což je transport, který klienti spouštějí lokálně. Během vývoje toto nespouštíte přímo; spouští to klient. Pro rychlý test funkčnosti použijte vývojový runner:

uv run mcp dev server.py

Krok 4: Vrácení čistého výstupu. Past, na kterou stojí za to upozornit hned teď: vracejte řetězec nebo typovanou hodnotu, nikoli holý vnořený slovník, u kterého doufáte, že se správně vykreslí. K tomu, proč to tak je, se vrátíme v sekci o produkci, ale stručně řečeno, nejednoznačné návratové typy mohou být v některých klientech tiše oříznuty.

To je kompletní MCP server v Pythonu. Dva nástroje, skutečná síťová volání, automatické schéma. Nyní totéž v TypeScriptu.

Jak vytvořit MCP server v TypeScriptu (krok za krokem)

Cesta přes TypeScript používá přímo oficiální TypeScript SDK a zod pro validaci vstupů. Je o něco upovídanější než FastMCP, ale typy jsou vynikající a nasazení na Node hostitele probíhá čistě.

Krok 1: Nastavení projektu.

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

Krok 2: Napsání serveru. Vytvořte 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: Spuštění. Během vývoje: npx tsx server.ts. Pro produkci zkompilujte pomocí tsc a spusťte sestavený .js s Node. Všimněte si tvaru návratové hodnoty: každý nástroj vrací { content: [{ type: "text", text: ... }] }. Toto explicitní pole content je ekvivalentem pravidla „vrátit čistý řetězec“ z Pythonu pro TypeScript. SDK vyžaduje typované bloky obsahu, nikoli surové objekty.

Krok 4: Validace vstupů pomocí zod. Schéma z.string().url() odmítne špatný vstup dříve, než se spustí váš handler, což je přesně to, co chcete, když model generuje argumenty.

Stejné dva nástroje, stejné chování, idiomatický TypeScript. Nyní se rozhodneme, jak by se klienti měli k vašemu serveru dostávat.

stdio vs Streamable HTTP: Který transport byste měli použít?

MCP servery komunikují prostřednictvím jednoho ze dvou transportů. stdio spouští server jako lokální podproces, který klient spustí a komunikuje s ním přes standardní vstup/výstup. Streamable HTTP provozuje server jako síťovou službu, ke které se klienti připojují přes HTTP. Výběr závisí na tom, kde musí server běžet.

Obecné pravidlo: vytvářejte a testujte na stdio a přepněte na Streamable HTTP pouze tehdy, když server potřebuje více než jedna osoba nebo stroj. Většina serverů nikdy nemusí opustit stdio. Volání mcp.run() a StdioServerTransport() výše jsou již stdio, takže pro vývoj jste připraveni.

Jak otestovat svůj MCP server pomocí Inspectoru

Než zapojíte svůj server do Claude, otestujte jej izolovaně pomocí MCP Inspectoru. Jedná se o prohlížečové UI, které se připojí k vašemu serveru, vypíše jeho nástroje a umožní vám je ručně volat. Spusťte jej proti vašemu serveru:

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

Inspector otevře místní stránku, kde můžete vidět své nástroje add a fetch_url, provést testovací volání a přečíst si surovou odpověď. To je jediný nejlepší návyk pro vývoj MCP. Pokud je schéma nástroje chybné nebo je návratová hodnota nesprávná, uvidíte to zde během sekund, místo abyste zírali na tiché selhání uvnitř Claude. Tímto způsobem jsme odhalili chybné vstupní schéma, které by nás jinak stálo celý cyklus ladění přes klienta. Nejprve vždy testujte v Inspectoru.

Jak připojit svůj MCP server k Claude Desktop, Claude Code a Cursor

Jakmile je Inspector spokojen, nasměrujte na svůj server skutečného klienta. Každý klient čte konfigurační soubor, který mu říká, jak spustit váš server přes stdio.

Claude Desktop. Upravte 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"]
    }
  }
}

Restartujte Claude Desktop a vaše nástroje se objeví pod ikonou konektorů.

Claude Code. Přidejte server jedním příkazem z vašeho projektu: claude mcp add demo-server -- uv run server.py. Claude Code jej uloží do konfigurace vašeho projektu a načte při spuštění. Pokud také používáte hooks ke skriptování Claude Code, náš průvodce hooks pro Claude Code se dobře doplňuje s vlastními nástroji MCP.

Cursor. Přidejte stejný blok mcpServers do .cursor/mcp.json v kořenovém adresáři vašeho projektu. Tvar odpovídá Claude Desktop. Pro příklad z praxe MCP serveru běžícího uvnitř Claude Code se podívejte, jak jsme zapojili Higgsfield do Claude Code.

V každé konfiguraci používejte absolutní cesty. Relativní cesty jsou nejčastějším důvodem, proč se server nespustí.

Nasazení MCP serveru do produkce (Autentizace a Hosting)

Když je třeba server sdílet, přesuňte jej ze stdio na Streamable HTTP a přidejte tři věci: autentizaci, zpracování chyb a hostitele.

• Autentizace. Vzdálené MCP servery musí používat OAuth 2.1 podle specifikace autorizace MCP. Pro interní nástroje je pragmatickým minimem kontrola bearer tokenu na HTTP endpointu. Nikdy neposílejte veřejný, neautentizovaný server nástrojů, protože nástroj, který spouští SQL nebo zasahuje do interních API, je živým útočným povrchem.
• Zpracování chyb. Zabalte těla nástrojů do try/except (nebo try/catch) a vraťte typovanou chybovou zprávu místo vyhazování výjimky. Model zvládá „dotaz selhal, zde je důvod“ mnohem lépe než přerušené připojení.
• Hosting. Funguje jakákoli platforma, která spouští dlouhotrvající proces Node nebo Python: malý VPS, Fly.io, Railway nebo kontejner na vaší vlastní infrastruktuře. Udržujte proces „teplý“, protože studené starty přidávají latenci prvnímu volání nástroje.
• Souběžnost a náklady. Pokud vaše nástroje volají LLM nebo placené API downstream, umístěte před ně bránu. Naše shrnutí nástrojů LLM gateway pokrývá omezování rychlosti a fallback a nástroje pro inženýrství kontextu pomáhají udržet výstupy nástrojů tak, aby nenafukovaly kontextové okno modelu.

Pro Python změňte volání run na mcp.run(transport="streamable-http"); pro TypeScript vyměňte StdioServerTransport za StreamableHTTPServerTransport z SDK. Definice nástrojů se vůbec nemění – to je pointou abstrakce transportu.

Co jsme se naučili při nasazování MCP serverů do produkce

V Techsy jsme vytvořili MCP servery pro interní použití a několik poučení se objeví až poté, co na ně narazí skutečný provoz. Zde je to, co jsme naměřili a kde nás to bolelo.

První server, který jsme vydali, byl nástroj pro dotazování do Postgresu pouze pro čtení, postavený s FastMCP 2.x na Python mcp 1.x SDK, později přepsaný do @modelcontextprotocol/sdk 1.x pro srovnání. Na stacku roku 2026 (Node 20, Python 3.11) přidala lokální volání nástrojů přes stdio přibližně 8 až 12 ms režie transportu na volání. Jakmile jsme přesunuli stejný server na Streamable HTTP na VPS, náklady na volání vzrostly na 40 až 70 ms, téměř výhradně kvůli síťovému round-tripu, nikoli nákladům protokolu. Studený start FastMCP trval asi 300 ms pro proces, proto udržujeme produkční proces teplý.

Past, která nás stála asi dvě hodiny: nástroj, který vracel surový Python dict, se v Inspectoru vykresloval dobře, ale v Claude Desktop přicházel oříznutý. Zabalení návratové hodnoty jako typovaného textového řetězce to okamžitě opravilo. Proto tento návod všude vrací řetězce a textové bloky content místo vnořených objektů. Dalším návykem, který se okamžitě vyplatil, bylo spuštění každého serveru přes npx @modelcontextprotocol/inspector před dotykem konfigurace klienta, což odhalilo chybné vstupní schéma při přepisu do TypeScriptu, které by jinak v Cursoru tiše selhalo.

Pokud vybíráte, které nástroje vůbec vestavět do serverů, náš seznam nejlepších MCP serverů v roce 2026 je dobrým zdrojem nápadů.

Jak Techsy přistupuje k vývoji MCP

V Techsy budujeme MCP servery jako součást systémů AI agentů, které dodáváme klientům, a propojujeme agenty s interními databázemi, CRM a API prostřednictvím typované vrstvy nástrojů. Naším přístupem je začít úzce (jeden dobře otestovaný nástroj přes stdio), ověřit ho v Inspectoru a poté jej povýšit na autentizovanou HTTP službu pouze tehdy, když ji potřebuje více než jeden agent. Vlastní servery kombinujeme s Claude Agent SDK, když se logika agenta stane složitou.

To je upřímná verze: většina týmů svůj první server příliš komplikuje. První den zřídka potřebujete HTTP, OAuth a tucet nástrojů. Pokud chcete druhý pár očí na integraci MCP, získejte bezplatnou konzultaci a my vám řekneme, zda jde o práci pro jeden nástroj přes stdio, nebo o něco, co skutečně potřebuje infrastrukturu.

Často kladené otázky

Měl bych budovat svůj MCP server v Pythonu nebo TypeScriptu?

Použijte to, co váš tým již vydává. Python s FastMCP je nejkratší cestou k prvnímu běžícímu serveru, protože dekorátor změní funkci na nástroj. TypeScript s oficiálním SDK je o něco upovídanější, ale poskytuje vynikající typy a čistě se nasazuje na Node hostitele. Obě možnosti vytvářejí servery, které se chovají vůči klientu identicky.

Potřebuji framework jako FastMCP k vytvoření MCP serveru?

Ne, ale pomáhá to. FastMCP je součástí oficiálního Python mcp SDK a odstraňuje většinu protokolové boilerplate kódu. Pro jemnější kontrolu můžete použít nízkoúrovňové API Server, ale pro téměř každý server je FastMCP (Python) nebo McpServer (TypeScript) tím správným nástrojem a vyžaduje mnohem méně kódu.

Jak ladit MCP server, který nefunguje?

Nejprve jej spusťte přes MCP Inspector: npx @modelcontextprotocol/inspector následovaný vaším spouštěcím příkazem. Inspector vypíše vaše nástroje a umožní vám je volat přímo, takže můžete potvrdit, že server funguje, než začnete obviňovat klienta. Pokud je Inspector v pořádku, ale klient ne, zkontrolujte, zda vaše konfigurace používá absolutní cesty a zda jste klienta restartovali.

Je FastMCP oficiální součástí MCP?

Ano. FastMCP je součástí oficiálního Python SDK Model Context Protocol jako vysoké rozhraní serveru. Dekorátor @mcp.tool(), který používáte, je doporučeným způsobem pro vytváření serverů v Pythonu, nikoli doplňkem třetí strany.

Jaký je rozdíl mezi lokálním a vzdáleným MCP serverem?

Lokální server běží na vašem stroji přes stdio, spuštěný klientem jako podproces, což je nejlepší pro osobní nástroje a vývoj. Vzdálený server běží jako webová služba přes Streamable HTTP a je dosažitelný pro více klientů, což vyžaduje autentizaci OAuth 2.1. Nejprve budujte lokálně, vzdáleně přecházejte pouze při sdílení.

V jakých jazycích mohu vytvořit MCP server?

Model Context Protocol má oficiální SDK pro Python, TypeScript, Javu, Kotlin a C#, s komunitními SDK v jiných jazycích. Protože MCP je wire protokol, jakýkoli jazyk, který umí číst a zapisovat JSON-RPC přes stdio nebo HTTP, může implementovat server, ale oficiální SDK vám tuto práci ušetří.

Funguje MCP server s ChatGPT a Gemini, nebo pouze s Claude?

MCP je otevřený standard přijatý v celém ekosystému agentní AI, včetně ChatGPT, Gemini, Cursor a VS Code Copilot. Jeden server, který vytvoříte, funguje s jakýmkoli kompatibilním klientem. Nepíšete samostatnou integraci pro každý model, což je celá pointa protokolu.

Jak dlouho trvá vytvoření funkčního MCP serveru?

První server s jedním nebo dvěma nástroji běžícími přes stdio zabere asi 15 minut po instalaci runtime. Naměřili jsme 14 minut pro začátečníka na Node 20 a méně než 5 minut pro opakované sestavení. Skutečný čas zabere přidání autentizace, HTTP transportu a produkčního hostingu, nikoli samotný server.

O autorovi

Mert Batur Gurbuz je spoluzakladatelem Techsy.io, kde tým dodává AI agenty, automatizační systémy a voice/SDR pipeline pro B2B klienty. Studuje na University of Birmingham a píše o stacku nástrojů LLM, který tým Techsy skutečně používá v produkci. Spojte se na LinkedIn.

Mert Batur Gurbuz, spoluzakladatel, Techsy.io, University of Birmingham