Model Context Protocol (MCP) 2026-ban: Gyakorlati útmutató MCP szerverek építéséhez Pythonban és TypeScriptben
Lépésről lépésre útmutató MCP szerverek építéséhez Pythonban (FastMCP) és TypeScriptben. Bekötés Claude Desktopba és Cursorba, OAuth 2.1 biztonság és a 2026-os legjobb gyakorlatok.
A Model Context Protocol (MCP) egy nyílt szabvány, amely egységesíti, hogyan kapcsolódnak az LLM-alapú alkalmazások külső adatforrásokhoz, eszközökhöz és kontextushoz. Gondolj rá úgy, mint az „USB-C portra" az AI ágensek számára. Az Anthropic 2024 novemberében publikálta a protokollt, és 2026 közepére az OpenAI, a Google DeepMind, a Microsoft Copilot Studio és a legtöbb komoly ágens-keretrendszer (LangChain, LlamaIndex, CrewAI) is támogatja. Ebben az útmutatóban egy működő MCP szervert építünk Pythonban és TypeScriptben, bekötjük Claude Desktopba és Cursorba, majd áttekintjük a 2026-os biztonsági és üzemeltetési legjobb gyakorlatokat.
Őszintén szólva, amikor először találkoztam az MCP-vel, kicsit szkeptikus voltam (még egy protokoll, tényleg?), de miután egy hétvégén átírtam egy belső LangChain tool-stacket MCP szerverekre, és ugyanazok a szerverek hirtelen elkezdtek működni Cursorban és Claude Desktopban is, megértettem, miért nem hype ez.
Az MCP egy JSON-RPC 2.0 alapú, kétirányú protokoll, amely három primitívre épül: tools (modell által hívható függvények), resources (olvasható kontextus) és prompts (újrahasznosítható sablonok).
A 2025-03-26-os specifikáció és a 2026-os 2025-06-18 verzió bevezette a Streamable HTTP transportot, az OAuth 2.1 alapú authorizációt és a strukturált tool outputokat.
A hivatalos SDK-k (Python, TypeScript, Java, C#, Kotlin, Swift, Ruby) lefedik a szerver és a kliens oldalt is. A FastMCP Pythonban néhány dekorátorral kész szervert ad.
Claude Desktop, Claude Code, Cursor, Zed, Windsurf és a VS Code Copilot mind natívan fogyaszt MCP szervereket. Egy szervert egyszerre több kliens is használhat.
Éles használathoz mindig adj jogosultság-szűrést, rate limitet, audit logot és (HTTP transport esetén) OAuth 2.1 + PKCE bejelentkezést.
A leggyakoribb hibák a transport-keverés, a hiányzó roots kezelés és a tool leírások túl szűkszavú megfogalmazása. Ezeket részletesen tárgyaljuk.
Mi az a Model Context Protocol és miért érdekes 2026-ban?
A Model Context Protocol az Anthropic által kezdeményezett nyílt protokoll, amely az LLM-alkalmazások és külső rendszerek közötti integrációt szabványosítja. Mielőtt megjelent, minden ágens-keretrendszer (LangChain, LlamaIndex, AutoGen, CrewAI) saját, inkompatibilis tool-formátumot használt. Egy GitHub integrációt mindhez külön kellett implementálni. Az MCP ezt az N×M problémát N+M-re csökkenti: egy MCP szervert egyszer írsz meg, és minden MCP-kompatibilis kliens (Claude Desktop, Cursor, Zed, VS Code Copilot, Windsurf, sőt 2026-tól az OpenAI Agents SDK is) használni tudja.
2026-ra a protokoll túljutott a korai fázison: a 2025-06-18-as verzió már GA-státuszú, a Streamable HTTP transport felváltotta a régi SSE-t, és az ökoszisztémában több mint 4000 nyilvános MCP szerver található (lásd a hivatalos MCP servers repót). A kulcs az, hogy az MCP nem egy újabb ágens-keretrendszer, hanem egy protokoll, ami alatt bármelyik keretrendszer fut.
MCP architektúra: host, kliens, szerver és a három primitív
Az MCP három szereplőt különít el. A host az LLM-et futtató alkalmazás (Claude Desktop, Cursor, saját ágens). A host minden összekapcsolt MCP szerverhez egy-egy kliens példányt indít (egy host több klienst is futtathat párhuzamosan). A szerver egy különálló folyamat (vagy HTTP endpoint), amely capabilities-t ad ki a kliensnek.
A protokoll három primitívet definiál, amit egy szerver felkínálhat:
Tools: modell által hívható függvények (pl. create_github_issue, run_sql_query). Mellékhatásuk lehet, paraméter-sémájuk JSON Schema.
Resources: olvasható kontextus URI-val azonosítva (pl. file:///docs/api.md, postgres://schema/users). Idempotensek, nincs mellékhatás.
Prompts: paraméterezhető prompt-sablonok, amiket a felhasználó kiválaszthat a klienseben (pl. „Review this PR" sablon).
Ezeken túl a kliens is felkínálhat capabilities-t a szervernek: sampling (a szerver kérhet LLM-completiont a kliens modelljétől), roots (a szerver megtudhatja, milyen fájlrendszer-gyökerek elérhetők), és 2026 óta elicitation (a szerver futás közben kérdezhet a felhasználótól). A kommunikáció JSON-RPC 2.0 üzenetekkel történik, kapacitás-egyeztetéssel kezdődik (initialize), és a kliens csak azokat a funkciókat hívhatja, amiket a szerver expliciten kihirdetett.
MCP szerver építése Pythonban (FastMCP)
A hivatalos Python SDK része a FastMCP magas szintű API, ami dekorátorokkal teszi lehetővé az MCP szerverek deklarálását. A példa egy egyszerű „Knowledge Base" szervert épít, ami egy lokális Markdown-mappát expose-ol tools és resources formájában.
A teljes szerver kódja (mentsd kb_server.py néven):
from pathlib import Path
from mcp.server.fastmcp import FastMCP
KB_ROOT = Path("/Users/me/notes").expanduser()
mcp = FastMCP("knowledge-base", version="1.0.0")
@mcp.resource("kb://{slug}")
def get_note(slug: str) -> str:
"Beolvas egy jegyzetet a tudásbázisból a megadott slug alapján."
path = KB_ROOT / f"{slug}.md"
if not path.is_file() or KB_ROOT not in path.resolve().parents:
raise FileNotFoundError(f"Nincs ilyen jegyzet: {slug}")
return path.read_text(encoding="utf-8")
@mcp.tool()
def search_notes(query: str, limit: int = 5) -> list[dict]:
"Kulcsszavas keresés a jegyzetek között. Visszaad max `limit` találatot."
results = []
q = query.lower()
for md in KB_ROOT.rglob("*.md"):
text = md.read_text(encoding="utf-8")
if q in text.lower():
snippet = text[:200].replace("\n", " ")
results.append({"slug": md.stem, "snippet": snippet})
if len(results) >= limit:
break
return results
@mcp.prompt()
def summarize_note(slug: str) -> str:
"Sablon: foglalja össze a megadott jegyzetet bullet pontokban."
return f"Olvasd be a kb://{slug} resource-t, majd készíts belőle 5 bullet pontos összefoglalót magyarul."
if __name__ == "__main__":
mcp.run(transport="stdio")
A három dekorátor a három primitívnek felel meg. A resource URI sablonja a {slug} path paramétert tartalmazza, és a kliens a teljes URI-t adja át (pl. kb://machine-learning). Figyeld meg a Path Traversal védelmet: ellenőrizzük, hogy a feloldott útvonal a KB_ROOT alatt van-e. Egy korábbi projektemben pont ezen a check-en csúsztam el, és egy elgépelt slug majdnem kivitt a notes mappából. Azóta mindig duplán ellenőrzöm.
Futtatás és tesztelés MCP Inspectorral:
mcp dev kb_server.py
# Megnyitja a böngészőben a http://localhost:5173 URL-t,
# ahol kipróbálhatod a toolokat és resource-okat.
MCP szerver építése TypeScriptben
A TypeScript SDK ugyanezt a fejlesztői élményt adja Node.js-en (≥ 18). Egy GitHub issue-kereső szervert építünk, ami a GitHub REST API-t expose-olja toolként.
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: "github-issues",
version: "1.0.0",
});
const GH_TOKEN = process.env.GITHUB_TOKEN;
if (!GH_TOKEN) throw new Error("GITHUB_TOKEN környezeti változó hiányzik");
server.tool(
"search_issues",
"GitHub issue-k keresése egy repóban címke és állapot szerint.",
{
repo: z.string().describe("owner/name formátum, pl. anthropics/sdk"),
state: z.enum(["open", "closed", "all"]).default("open"),
label: z.string().optional(),
limit: z.number().int().min(1).max(50).default(10),
},
async ({ repo, state, label, limit }) => {
const params = new URLSearchParams({ state, per_page: String(limit) });
if (label) params.set("labels", label);
const res = await fetch(
`https://api.github.com/repos/${repo}/issues?${params}`,
{
headers: {
Authorization: `Bearer ${GH_TOKEN}`,
Accept: "application/vnd.github+json",
},
},
);
if (!res.ok) {
return {
content: [{ type: "text", text: `GitHub API hiba: ${res.status}` }],
isError: true,
};
}
const issues = (await res.json()) as Array<{
number: number;
title: string;
html_url: string;
state: string;
}>;
return {
content: [
{
type: "text",
text: issues
.map((i) => `#${i.number} [${i.state}] ${i.title}\n${i.html_url}`)
.join("\n\n"),
},
],
};
},
);
const transport = new StdioServerTransport();
await server.connect(transport);
Néhány dolog, ami eltér a Python változattól: a zod sémából automatikusan generál a runtime JSON Schemát; a tool válasza egy content tömb (text vagy image item-ekkel), és isError: true-val jelezzük a tool-szintű hibát. Ez fontos, mert a modell ekkor megkapja a hibaüzenetet és újrapróbálhatja.
Indítás: npx tsx src/server.ts, de stdio transport esetén normálisan a kliens indítja el a folyamatot.
Hogyan kötöd be Claude Desktopba és Cursorba?
Claude Desktopban a szerver konfigurációja a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) vagy a %APPDATA%\Claude\claude_desktop_config.json (Windows) fájlban történik:
A Claude Desktop újraindítása után a chat-mezőben egy „🔌" ikon jelzi a csatlakoztatott szervereket. A toolok a felhasználó engedélye után hívhatók (per-hívás vagy per-szerver engedély).
Cursorban a .cursor/mcp.json fájlba ugyanezt a struktúrát teszed, projekt-szinten. A Cursor 2026-os verziója már támogatja a Streamable HTTP transportot is, így távoli szervereket is be tudsz kötni:
Stdio vs Streamable HTTP: melyik transportot válaszd?
A 2025-03-26-os specifikáció óta az MCP-nek két hivatalos transportja van: stdio (stdin/stdout pipe) és Streamable HTTP (HTTP POST + opcionális SSE válasz-stream). A régi „HTTP + SSE" transport elavult, új projektben ne használd.
Szempont
Stdio
Streamable HTTP
Tipikus használat
Lokális, egy-felhasználós eszközök (CLI-szerű)
Megosztott / távoli szerverek, csapatszintű telepítés
Auth
OS-szintű (a kliens indítja, ugyanaz a user)
OAuth 2.1 + PKCE (kötelező scope-okkal)
Telepítés
Klienseként konfigurálni kell (config fájl)
URL beillesztése, megosztható linkként
Skálázás
1 felhasználó / 1 folyamat
Sok kliens / 1 szerver, horizontális skálázás
Streamelt válasz
Igen (stdout)
Igen (SSE a POST válaszban)
Mikor válaszd?
Helyi fájlok, lokális CLI eszközök, fejlesztés
SaaS integrációk, vállalati belső API-k, multi-user
Általános ökölszabály: ha a szerver csak az adott felhasználó gépén futó erőforrásokat ér el (fájlok, lokális Postgres, helyi git repo), válaszd a stdio transportot. Egyszerűbb, és nincs auth komplexitás. Ha a szerver központi szolgáltatás (vállalati Confluence, megosztott adattó, SaaS API), Streamable HTTP-re lesz szükséged. A Python SDK-ban a mcp.run(transport="streamable-http", host="0.0.0.0", port=8000) sorral indítható.
Na, itt jön a rész, amit senki nem szeret, de mindenki ráfizet, ha kihagyja. Az MCP nem oldja meg a biztonsági kérdéseket helyetted, ezek a szerver és a host felelősségei. 2026-ban a következő rétegeket kell felépítened:
1. Authentikáció (OAuth 2.1 HTTP transport esetén)
A 2025-06-18 specifikáció kötelezővé tette az OAuth 2.1-et PKCE-vel a HTTP transportokhoz. A szerver közzéteszi a Protected Resource Metadatát a /.well-known/oauth-protected-resource endpointon, a kliens pedig az Authorization Server discovery alapján szerez tokent. Soha ne implementálj saját bearer-token sémát, használj megbízható IdP-t (Auth0, Clerk, Authentik, Keycloak).
2. Authorizáció (scope-ok és per-tool jogosultság)
Minden tool-hoz definiálj scope-ot, és a tool meghívásánál ellenőrizd a token scope-jait. A least privilege elve itt is érvényes: ne adj repo:write scope-ot, ha csak olvasol.
3. Prompt injection ellen védelem
A resource-okból visszaadott szöveg modell-bemenet lesz, ezért a szerver soha nem szabad, hogy „bízzon" külső tartalmakban. Gyakorlati lépések: jelöld meg a külső forrásokat egyértelmű delimiterrel (<untrusted>…</untrusted>), strippeld a system-prompt-szerű utasításokat, és a tool-leírásokban se használj olyan kifejezéseket, amik direkt utasításnak tűnhetnek a modellnek.
4. Audit log és rate limiting
Minden tool-hívást logolj (ki, mikor, milyen paraméterekkel, milyen eredménnyel), és tegyél rate limitet a destruktív műveletekre. A LLM observability 2026-ban cikkben tárgyalt eszközök (Langfuse, Phoenix) 2026 óta natívan értik az MCP eseményeket.
Hibakeresés: MCP Inspector és gyakori csapdák
Az MCP Inspector (Anthropic hivatalos eszköze) egy webes UI, ami kliens-szimulátorként működik. Indítás:
npx @modelcontextprotocol/inspector node ./dist/server.js
# Megnyit egy http://localhost:6274 URL-t, ahol minden
# JSON-RPC üzenetet láthatsz forgatókönyv-szerűen.
Gyakori csapdák, amikkel a fejlesztők találkoznak (és bevallom, én is mindegyiken átestem):
Stdio transport: ne nyomtass stdout-ra. A print() Pythonban vagy a console.log TypeScriptben a JSON-RPC csatornába ír, és törli a kapcsolatot. Minden naplózást stderr-re irányíts (logging.basicConfig(stream=sys.stderr)).
Roots figyelmen kívül hagyása. A kliens elküldi a roots listát (engedélyezett fájlrendszer-területek). Ha kihagyod, a tool olyan fájlokhoz nyúl, amikhez a felhasználó nem adott engedélyt.
Túl szűk tool-leírás. Ha a docstring 1 mondat, a modell nem fogja eltalálni, mikor hívja. Írj 2–4 mondatos leírást példa-használattal: „Use when the user asks about open GitHub issues. Example: 'show open bugs in anthropic/sdk' → repo='anthropic/sdk', label='bug'."
Hiányzó error handling. A tool kivétele lefagyaszthatja a szervert. Mindig csomagold try/except-be, és térj vissza isError: true válasszal.
Verzió-mismatch. A kliens és szerver különböző protocol verziókat tárgyalhat. Tartsd az SDK-t naprakészen, és tartsd be a 2025-06-18 minimumot új szerverekhez.
MCP vs. natív function calling: mikor melyiket?
Felmerül a kérdés: ha az Anthropic API-nak van saját tools paramétere (és az OpenAI-nak is), mi a különbség az MCP-hez képest? A válasz: a natív function calling a modell ↔ API-hívó kód közti protokoll. Az MCP ennél eggyel feljebb van, az API-hívó kód ↔ külső eszköz/adatforrás közti protokoll. A kettő nem helyettesítője egymásnak.
Egy tipikus production setup így néz ki:
A modell function callingot használ (Claude tool use / OpenAI tools).
A te ügyfél-kódod (host) MCP-n keresztül beszél a tool-implementációkkal (szerverek).
A szerverek a háttér-rendszerekkel beszélnek (DB, SaaS API, fájlrendszer).
Ez a réteges szétválasztás teszi lehetővé, hogy egy MCP szervert egyszerre Claude, GPT-4.5, Gemini és Llama-alapú ágensek is használjanak. A function calling formátum különbségei a kliensben oldódnak fel. Ha többágenses rendszert építesz, érdemes a többágenses AI orkesztráció 2026-ban cikkben tárgyalt mintákat kombinálni MCP szerverekkel, így minden ágens ugyanazokat a megosztott eszközöket éri el konzisztensen.
Gyakran ismételt kérdések
Mi a különbség az MCP és a LangChain Tools között?
A LangChain Tools egy keretrendszer-specifikus Python API tool-ok definiálására. Az MCP egy nyelv- és keretrendszer-független protokoll. Egy MCP szerver bármelyik MCP-képes kliensből (LangChain, LlamaIndex, Claude Desktop, Cursor) használható; egy LangChain Tool csak LangChain alkalmazásban. 2026 óta a LangChain natívan tudja használni az MCP szervereket Toolként, így a két réteg jól megfér egymás mellett.
Lehet egy MCP szervert egyszerre több klienssel használni?
Stdio transport esetén nem, mert minden kliens saját szerver-folyamatot indít. Streamable HTTP transport esetén igen: egy szerver-példány több párhuzamos kliens-sessiont tud kezelni, ahol minden sessiont egy egyedi Mcp-Session-Id header azonosít. Ezt használják a vállalati központi MCP szerverek (pl. egy közös belső dokumentum-keresés).
Hogyan kezelje az MCP szerver a hosszú futási idejű műveleteket?
Streamable HTTP transport esetén a tool válasza streamelhető SSE eventekkel, így progress üzeneteket küldhetsz a kliensnek. A 2025-06-18-as spec bevezette a notifications/progress üzeneteket is, amik token-szintű streamhez hasonlóan jelzik az előrehaladást. Stdio transportnál ugyanezt JSON-RPC notification-okkal éred el. Ha a művelet több percig is eltarthat, érdemes job ID-t visszaadni és külön tool-lal kérdezni le az állapotot.
Mi a teendő, ha az MCP szerver nem jelenik meg Claude Desktopban?
Először ellenőrizd a Claude Desktop logokat (~/Library/Logs/Claude/mcp*.log macOS-en). A leggyakoribb okok: 1) abszolút path helyett relatív path a command mezőben, 2) a stdio szerver stdout-ra naplóz (nem stderr-re), 3) a környezeti változók hiányoznak az env blokkból (Claude Desktop nem örökli a shell envet), 4) a config fájl JSON-jában szintaktikai hiba van. Az MCP Inspectorral izoláltan tudod tesztelni a szervert.
Az MCP csak Anthropic Claude-dal működik?
Nem. Az MCP nyílt szabvány, és 2026-ra az OpenAI Agents SDK, a Google Vertex AI Agent Builder, a Microsoft Copilot Studio és számos open-source ágens-keretrendszer (LangChain, LlamaIndex, CrewAI, AutoGen) is natívan támogatja kliens-oldalon. Bár az Anthropic kezdeményezte, a specifikáció nyíltan kormányzott és bármelyik modell-szolgáltatóval kompatibilis.
