Salt la conținutul principal
Română— Alege o limbă
Meniu

Arhitectura unui server MCP personalizat

Lecția 10 din 14 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Proiectarea unui server MCP de producție
  2. Alegerea framework-ului
  3. O structură de proiect durabilă
  4. Punctul de intrare: server.py
  5. Un modul de unelte per domeniu
  6. Configurație centralizată
  7. Erori lizibile pentru model
  8. Cu stare (Stateful) sau fără stare (Stateless)
  9. Puncte cheie

Actualizat la 2 noiembrie 2026 — MCP Python SDK v2. Acest curs urmează acum versiunea 2 a SDK-ului mcp (2.3.0 la data de 2 octombrie 2026): MCPServer înlocuiește FastMCP, setările de transport se mută în run() sau streamable_http_app(), iar o aplicație expusă sub un nume de gazdă real trebuie să declare acel nume de gazdă (transport_security). Aceasta este, de asemenea, versiunea cerută de Mistral SDK: extra-ul mistralai[agents] necesită mcp>=2.2.0,<3.0. Surse: Ce este nou în v2 · Ghid de migrare · Deploy & scale.

Proiectarea unui server MCP de producție

Un prototip MCP încap într-un fișier de patruzeci de linii, iar acest lucru este adesea suficient pentru a convinge o echipă. Trecerea la utilizarea în lumea reală schimbă totul: mai multe persoane apelează serverul, uneltele se înmulțesc, configurația variază între medii, iar fișierul unic devine imposibil de întreținut. Această lecție acoperă deciziile arhitecturale care previn lovirea acestui zid: alegerea unui framework, structurarea proiectului, gestionarea configurației și a erorilor, precum și alegerea între servere cu stare (stateful) și fără stare (stateless).

Alegerea framework-ului

În Python, clasa MCPServer din SDK-ul oficial (fostul FastMCP) este instrumentul standard. Aceasta expune un API bazat pe decoratori și gestionează protocolul MCP în locul dumneavoastră, astfel încât un server prinde viață în trei linii:

from mcp.server.mcpserver import MCPServer

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

Echipele care lucrează în JavaScript și TypeScript au la dispoziție SDK-ul MCP oficial publicat de Anthropic. Logica este comparabilă, chiar dacă sintaxa diferă:

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

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

Alegerea depinde mai puțin de capacități și mai mult de ecosistemul din care serverul dumneavoastră își va prelua datele. Un server care interoghează o bază de date prin SQLAlchemy sau care reutilizează scripturi de procesare existente va fi natural în Python; un server susținut de o aplicație Express existentă va rămâne în TypeScript. Tabelul de mai jos rezumă diferențele practice.

CriteriuMCPServer (Python SDK)MCP SDK (TypeScript)
MaturitateFoarte maturMatur
Decoratori@app.tool()Metoda server.tool()
Transport HTTPIntegrat (FastAPI)Integrat (Express)
ComunitateMareMare

O structură de proiect durabilă

Structura de directoare recomandată separă patru responsabilități: ceea ce vede modelul (tools/), ceea ce accesează datele (services/), ceea ce controlează accesul (auth/) și ceea ce descrie mediul (config.py, .env).

my-mcp-server/
├── server.py              # Punct de intrare FastAPI + montare MCP
├── tools/
│   ├── __init__.py
│   ├── project_tools.py   # Unelte de gestionare a proiectelor
│   ├── file_tools.py      # Unelte de gestionare a fișierelor
│   └── search_tools.py    # Unelte de căutare
├── services/
│   ├── __init__.py
│   ├── database.py        # Acces la baza de date
│   └── external_api.py    # Apeluri API externe
├── auth/
│   ├── __init__.py
│   └── middleware.py       # Middleware de autentificare
├── config.py              # Configurație (variabile de mediu)
├── Dockerfile             # Containerizare
├── requirements.txt       # Dependențe Python
├── .env                   # Variabile de mediu (necomise în repo)
└── tests/
    ├── test_tools.py
    └── test_integration.py

Această separare are o consecință directă și concretă: uneltele dumneavoastră nu mai conțin apeluri SQL sau HTTP, ci doar validare și delegare către un serviciu. Astfel, puteți testa logica de afaceri fără a trece prin MCP și puteți schimba bazele de date fără a atinge niciun docstring pe care îl vede modelul.

Punctul de intrare: server.py

Fișierul principal nu face nimic altceva decât să asambleze componentele: creează aplicația FastAPI, stivuiește middleware-urile și montează fiecare server MCP pe propria sa rută.

# server.py
"""Punct de intrare pentru serverul MCP."""

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

# Fiecare server MCP trebuie să își pornească managerul de sesiune
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
        yield

# Aplicație FastAPI
api = FastAPI(
    title="My MCP Server",
    version="1.0.0",
    lifespan=lifespan,
)

# CORS pentru clienți web
api.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

# Middleware de autentificare
api.add_middleware(AuthMiddleware)

# Numele de gazdă public sub care sunt deservite serverele (altfel: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])

# Montarea serverelor MCP pe rute distincte
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))

# Pagina de start (opțională, dar utilă)
@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)

Montarea pe rute distincte permite utilizatorilor să activeze doar domeniul de care au nevoie: cineva care caută documentație se conectează la /search/mcp fără a i se oferi unelte de gestionare a proiectelor. Cât despre pagina de start, aceasta pare trivială până când un coleg întreabă URL-ul exact al endpoint-ului; ea răspunde în locul dumneavoastră și servește drept verificare a stării de sănătate (health check).

Un modul de unelte per domeniu

Fiecare fișier din folderul tools/ declară propriul obiect MCPServer și grupează uneltele din același domeniu funcțional. Iată cum arată modulul de gestionare a proiectelor, importat anterior de server.py:

# tools/project_tools.py
"""Unelte MCP pentru gestionarea proiectelor."""

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:
    """Creează un nou proiect.

    Args:
        name: Numele proiectului (2-100 caractere)
        description: Descrierea proiectului (opțional)

    Returns:
        JSON cu detaliile proiectului creat
    """
    project = await db.projects.create(name=name, description=description)
    return project.to_json()

@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
    """Listează proiectele după statut.

    Args:
        status: Filtrare după statut: active, archived, all (implicit: active)

    Returns:
        JSON cu lista de proiecte
    """
    projects = await db.projects.list(status=status)
    return projects.to_json()

Observați cât de scurte sunt corpurile funcțiilor: doar două linii fiecare, deoarece accesul la date trăiește în services/database.py. Unealta descrie pur și simplu contractul său modelului și deleagă execuția.

Configurație centralizată

Orice valoare care se schimbă între mașina dumneavoastră și serverul de producție trebuie să provină din mediul de execuție, niciodată din cod. Un singur fișier config.py reunește aceste variabile împreună cu valorile lor implicite:

# config.py
"""Configurație server MCP."""

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()

Parametrul max_results ilustrează beneficiul acestei abordări: în ziua în care o unealtă returnează prea multe rezultate și saturează contextul modelului, ajustați o variabilă de mediu și reporniți, fără a redeploy-a codul.

Erori lizibile pentru model

O excepție Python care urcă brusc la suprafață nu spune nimic modelului: acesta vede o eșuare fără a înțelege de ce și adesea reîncearcă identic. În schimb, standardizați un format explicit de răspuns la eroare, cu un cod și un mesaj.

import json

def error_response(message: str, code: str = "error") -> str:
    """Formatează un mesaj de eroare standardizat."""
    return json.dumps({
        "success": False,
        "error": {"code": code, "message": message}
    }, ensure_ascii=False)

@project_mcp.tool()
async def get_project(project_id: str) -> str:
    """Recuperează detaliile proiectului după 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")

Diferența este decisivă în conversație. În fața lui not_found, modelul înțelege că trebuie mai întâi să listeze proiectele pentru a găsi ID-ul corect; în fața unei excepții silențioase, renunță sau intră în buclă.

Cu stare (Stateful) sau fără stare (Stateless)

Un server cu stare (stateful) păstrează informații între apeluri: bază de date în memorie, sesiuni de utilizator, context de lucru. Acest lucru este comun pentru serverele de gestionare, cum ar fi managerul de sarcini din lecția anterioară. Un server fără stare (stateless) gestionează fiecare cerere independent, fără a reține nimic – recomandat pentru calcul pur sau transformare și permițând scalarea orizontală, deoarece orice instanță poate gestiona orice cerere. SDK v2 permite acest lucru printr-un parametru al aplicației HTTP (nu mai este transmis constructorului). Rețineți că, odată cu specificația din 28-07-2026, protocolul în sine nu mai cunoaște sesiunile: această setare privește doar clienții care negociază o versiune anterioară a protocolului.

app = MCPServer("Stateless Server")

# Setarea este transmisă la construirea aplicației HTTP
mcp_app = app.streamable_http_app(stateless_http=True)

Decideți această chestiune înainte de a scrie uneltele, nu după: trecerea de la un server cu stare la unul fără stare implică mutarea întregii stări într-o bază de date externă, ceea ce rescrie o bună parte din cod.

Puncte cheie

  • Separați uneltele în module tematice într-un folder tools/
  • Folosiți FastAPI ca bază HTTP, montați serverele MCP pe rute dedicate și transmiteți-le lifespan
  • Centralizați configurația prin variabile de mediu
  • Standardizați formatele de răspuns la eroare pentru ca modelul să le poată utiliza
  • Alegeți între cu stare (gestionarea datelor) și fără stare (calcul pur)
  • Adăugați o pagină de start / pentru a documenta endpoint-urile dumneavoastră MCP