Egyéni MCP-kiszolgáló architektúrája
Ezen az oldalon
Frissítve: 2026. november 2. — MCP Python SDK v2. Ez a tanfolyam az
mcpSDK 2-es verzióját követi (2026. október 2-i állapot szerint 2.3.0): azMCPServerleváltja aFastMCP-t, a transzportbeállítások arun()vagystreamable_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: amistralai[agents]extra függőségéhezmcp>=2.2.0,<3.0szü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érium | MCPServer (Python SDK) | MCP SDK (TypeScript) |
|---|---|---|
| Érettség | Nagyon érett | Érett |
| Dekorátorok | @app.tool() | server.tool() metódus |
| HTTP Transzport | Beépített (FastAPI) | Beépített (Express) |
| Közösség | Nagy | Nagy |
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