Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Egyéni MCP-kiszolgáló architektúrája

10. lecke 14 közül Frissítve 2026. november 2. Fejlesztő
Ezen az oldalon
  1. Produkciós MCP-kiszolgáló tervezése
  2. A keretrendszer kiválasztása
  3. Tartós projektstruktúra
  4. A belépési pont: server.py
  5. Egy eszközmodul domainenként
  6. Központosított konfiguráció
  7. A modell által olvasható hibák
  8. Állapotkezelő vagy állapotmentes
  9. Főbb megállapítások

Frissítve: 2026. november 2. — MCP Python SDK v2. Ez a tanfolyam az mcp SDK 2-es verzióját követi (2026. október 2-i állapot szerint 2.3.0): az MCPServer leváltja a FastMCP-t, a transzportbeállítások a run() vagy streamable_http_app() metódusokba kerültek, és egy valódi hosztnév alatt elérhető alkalmazásnak deklarálnia kell ezt a hosztnevet (transport_security). Ez az a verzió, amelyet a Mistral SDK is megkövetel: a mistralai[agents] extra függőségéhez mcp>=2.2.0,<3.0 szükséges. Források: Újdonságok a v2-ben · Migrációs útmutató · Üzembe helyezés és skálázás.

Produkciós MCP-kiszolgáló tervezése

Egy MCP-prototípus elfér negyven soros fájlban, és ez gyakran elég ahhoz, hogy meggyőzz egy csapatot. A valós használatra való áttérés azonban mindent megváltoztat: többen hívják meg a kiszolgálót, szaporodnak az eszközök, a konfiguráció környezetenként változik, és az egyetlen fájl karbantarthatatlanná válik. Ez a lecke azokat az architektúrális döntéseket tárgyalja, amelyekkel elkerülheted ezt a falat: keretrendszer választása, projektstruktúra kialakítása, konfiguráció és hibakezelés menedzselése, valamint döntés az állapotmentes és állapotot kezelő kiszolgálók között.

A keretrendszer kiválasztása

Pythonban a hivatalos SDK MCPServer osztálya (korábban FastMCP) a szabványos eszköz. Dekorátorokon alapuló API-t biztosít, és kezeli helyetted az MCP protokollt, így három sorral életre kelthetsz egy kiszolgálót:

from mcp.server.mcpserver import MCPServer

app = MCPServer(
    "My Server",
    instructions="MCP Server for project management",
)

A JavaScript és TypeScript csapatok az Anthropic által közzétett hivatalos MCP SDK-t használhatják. A logika hasonló, még ha a szintaxis különbözik is:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

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

A választás kevésbé függ a képességektől, annál inkább attól az ökoszisztémától, ahonnan a kiszolgálód az adatait lekéri. Egy SQLAlchemy-n keresztül adatbázist lekérő vagy meglévő feldolgozó szkripteket újrahasznosító kiszolgáló természetesen Pythonban készül; egy meglévő Express alkalmazásra épülő kiszolgáló TypeScriptben marad. Az alábbi táblázat összefoglalja a gyakorlati különbségeket.

KritériumMCPServer (Python SDK)MCP SDK (TypeScript)
ÉrettségNagyon érettÉrett
Dekorátorok@app.tool()server.tool() metódus
HTTP TranszportBeépített (FastAPI)Beépített (Express)
KözösségNagyNagy

Tartós projektstruktúra

A javasolt könyvtárszerkezet négy felelősségi kört választ szét: amit a modell lát (tools/), ami az adatokhoz fér hozzá (services/), ami a hozzáférést vezérli (auth/), és ami a környezetet írja le (config.py, .env).

my-mcp-server/
├── server.py              # FastAPI belépési pont + MCP csatlakoztatás
├── tools/
│   ├── __init__.py
│   ├── project_tools.py   # Projektmenedzsment eszközök
│   ├── file_tools.py      # Fájlkezelési eszközök
│   └── search_tools.py    # Keresési eszközök
├── services/
│   ├── __init__.py
│   ├── database.py        # Adatbázis-hozzáférés
│   └── external_api.py    # Külső API-hívások
├── auth/
│   ├── __init__.py
│   └── middleware.py       # Hitelesítési middleware
├── config.py              # Konfiguráció (környezeti változók)
├── Dockerfile             # Konténeresítés
├── requirements.txt       # Python függőségek
├── .env                   # Környezeti változók (nem commitolva)
└── tests/
    ├── test_tools.py
    └── test_integration.py

Ennek a szétválasztásnak közvetlen, kézzelfogható következménye van: az eszközeid már nem tartalmaznak SQL vagy HTTP hívásokat, csak validálást és delegálást egy szolgáltatás felé. Így az üzleti logikát tesztelheted az MCP megkerülésével, és adatbázist válthatsz anélkül, hogy egyetlen, a modell által látott docstringet is módosítanál.

A belépési pont: server.py

A főfájl nem csinál mást, mint összeszereli az összetevőket: létrehozza a FastAPI alkalmazást, egymásra helyezi a middleware-eket, és minden egyes MCP-kiszolgálót saját útvonalra csatlakoztat.

# server.py
"""MCP server entry point."""

from contextlib import asynccontextmanager

import os

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from mcp.server.transport_security import TransportSecuritySettings
from tools.project_tools import project_mcp
from tools.search_tools import search_mcp
from auth.middleware import AuthMiddleware

# Minden MCP-kiszolgálónak el kell indítania a munkamenet-kezelőjét
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
        yield

# FastAPI alkalmazás
api = FastAPI(
    title="My MCP Server",
    version="1.0.0",
    lifespan=lifespan,
)

# CORS webes kliensek számára
api.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

# Hitelesítési middleware
api.add_middleware(AuthMiddleware)

# Nyilvános hosztnév, amely alatt a kiszolgálók elérhetők (különben: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])

# MCP-kiszolgálók csatlakoztatása külön útvonalakra
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))

# Kezdőlap (opcionális, de hasznos)
@api.get("/")
async def root():
    return {
        "service": "My MCP Server",
        "version": "1.0.0",
        "endpoints": {
            "projects": "/projects/mcp",
            "search": "/search/mcp",
        },
    }

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(api, host="0.0.0.0", port=8000)

A külön útvonalakra való csatlakoztatás lehetővé teszi, hogy a felhasználók csak azt a domaint engedélyezzék, amire szükségük van: valaki, aki dokumentációt keres, a /search/mcp végponthoz csatlakozik anélkül, hogy projektmenedzsment eszközöket kínálnának fel neki. Ami a kezdőlapot illeti, triviálisnak tűnik mindaddig, amíg egy kolléga rá nem kérdez a pontos végpont URL-re; ez helyetted válaszol, és egészségellenőrzésként is szolgál.

Egy eszközmodul domainenként

A tools/ mappa minden egyes fájlja saját MCPServer objektumot deklarál, és azonos funkcionális domainből származó eszközöket csoportosít. Íme, hogyan néz ki a projektmenedzsment modul, amelyet a server.py korábban importált:

# tools/project_tools.py
"""MCP tools for project management."""

from mcp.server.mcpserver import MCPServer
from services.database import db

project_mcp = MCPServer(
    "Project Manager",
    instructions="Tools for project and task management",
)

@project_mcp.tool()
async def create_project(name: str, description: str = "") -> str:
    """Creates a new project.

    Args:
        name: Project name (2-100 characters)
        description: Project description (optional)

    Returns:
        JSON with created project details
    """
    project = await db.projects.create(name=name, description=description)
    return project.to_json()

@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
    """Lists projects by status.

    Args:
        status: Filter by status: active, archived, all (default: active)

    Returns:
        JSON with list of projects
    """
    projects = await db.projects.list(status=status)
    return projects.to_json()

Figyeld meg, milyen rövidek a függvény törzsei: mindössze két sor, mert az adathozzáférés a services/database.py fájlban él. Az eszköz csupán leírja a szerződését a modell számára, és delegál.

Központosított konfiguráció

Bármilyen érték, amely a géped és a produkciós kiszolgáló között változik, a környezetből kell származzon, soha nem a kódból. Egyetlen config.py fájl gyűjti össze ezeket a változókat alapértelmezett értékeikkel:

# config.py
"""MCP server configuration."""

import os
from dataclasses import dataclass

@dataclass
class Config:
    api_token: str = os.getenv("MCP_API_TOKEN", "")
    database_url: str = os.getenv("DATABASE_URL", "sqlite:///data.db")
    debug: bool = os.getenv("DEBUG", "false").lower() == "true"
    port: int = int(os.getenv("PORT", "8000"))
    max_results: int = int(os.getenv("MAX_RESULTS", "50"))

config = Config()

A max_results paraméter szemlélteti ennek a megközelítésnek az előnyét: azon a napon, amikor egy eszköz túl sok találatot ad vissza, és telíti a modell kontextusát, módosítasz egy környezeti változót és újraindítasz, anélkül, hogy újra üzembe helyeznéd a kódot.

A modell által olvasható hibák

Egy Python kivétel, amely hirtelen a felszínre tör, semmit sem mond a modellnek: hibát lát, de nem érti, miért, és gyakran ugyanúgy próbálkozik újra. Ehelyett szabványosíts egy explicit hiba-válasz formátumot kóddal és üzenettel.

import json

def error_response(message: str, code: str = "error") -> str:
    """Formats a standardized error message."""
    return json.dumps({
        "success": False,
        "error": {"code": code, "message": message}
    }, ensure_ascii=False)

@project_mcp.tool()
async def get_project(project_id: str) -> str:
    """Retrieves project details by ID."""
    try:
        project = await db.projects.get(project_id)
        if not project:
            return error_response(f"Project {project_id} not found", "not_found")
        return project.to_json()
    except Exception as e:
        return error_response(f"Server error: {str(e)}", "server_error")

A különbség döntő a beszélgetés során. A not_found láttán a modell megérti, hogy először listáznia kell a projekteket a megfelelő azonosító megtalálásához; egy csendes kivétel esetén viszont feladja vagy körbe-körbe jár.

Állapotkezelő vagy állapotmentes

Egy állapotkezelő (stateful) kiszolgáló megjegyzi az információkat a hívások között: memóriabeli adatbázis, felhasználói munkamenetek, munkakörnyezet. Ez gyakori menedzsment kiszolgálóknál, mint az előző leckében szereplő feladatkezelő. Egy állapotmentes (stateless) kiszolgáló minden kérést függetlenül kezel, és nem emlékszik semmire – ez tiszta számításokhoz vagy transzformációkhoz ajánlott, és lehetővé teszi a vízszintes skálázást, mivel bármely példány kezelhet bármely kérést. Az SDK v2 ezt egy HTTP alkalmazás paraméterrel teszi lehetővé (már nem a konstruktorban adjuk át). Ne feledd, hogy a 2026-07-28-i specifikációval maga a protokoll már nem ismeri a munkameneteket: ez a beállítás csak azokat a klienseket érinti, amelyek korábbi protokollverziót tárgyalnak ki.

app = MCPServer("Stateless Server")

# A beállítás átadása a HTTP alkalmazás létrehozásakor történik
mcp_app = app.streamable_http_app(stateless_http=True)

Döntsd el ezt a kérdést az eszközök megírása előtt, ne utána: az állapotkezelőből állapotmentes kiszolgálóvá válás azt jelenti, hogy az összes állapotot külső adatbázisba kell helyezni, ami a kód jó részének átírását igényli.

Főbb megállapítások

  • Válaszd szét az eszközeidet tematikus modulokra egy tools/ mappában
  • Használd a FastAPI-t HTTP alapként, csatlakoztasd az MCP-kiszolgálókat dedikált útvonalakra, és add át a lifespan kezelőjüket
  • Központosítsd a konfigurációt környezeti változókon keresztül
  • Szabványosítsd a hiba-válasz formátumokat, hogy a modell használni tudja őket
  • Válassz az állapotkezelő (adatkezelés) és állapotmentes (tiszta számítás) között
  • Adj hozzá egy / kezdőlapot az MCP végpontjaid dokumentálásához