Architektúra vlastného MCP servera
Na tejto strane
Aktualizované 2. novembra 2026 — MCP Python SDK v2. Tento kurz teraz nasleduje verziu 2 SDK
mcp(2.3.0 k 2. októbru 2026):MCPServernahrádzaFastMCP, nastavenia transportu sa presúvajú dorun()alebostreamable_http_app()a aplikácia vystavená pod skutočným hostname musí tento hostname deklarovať (transport_security). Toto je tiež verzia požadovaná Mistral SDK: extra balíkmistralai[agents]vyžadujemcp>=2.2.0,<3.0. Zdroje: Čo je nové vo v2 · Sprievodca migráciou · Nasadenie a škálovanie.
Návrh produkčného MCP servera
Prototyp MCP sa zmestí do súboru so štyridsiatimi riadkami a to často stačí na presvedčenie tímu. Prechod na reálne použitie však mení všetko: server volá viacero ľudí, nástroje sa množia, konfigurácia sa líši podľa prostredia a jeden súbor sa stáva neudržateľným. Táto lekcia pokrýva architektonické rozhodnutia, ktoré ti pomôžu vyhnúť sa tejto stene – výber frameworku, štruktúrovanie projektu, správa konfigurácie a chýb a rozhodovanie medzi stavovými a bezstavovými servermi.
Výber tvojho frameworku
V Pythone je trieda MCPServer z oficiálneho SDK (predtým FastMCP) štandardným nástrojom. Poskytuje API založené na dekorátoroch a za teba vybavuje protokol MCP, takže server ožije na tri riadky:
from mcp.server.mcpserver import MCPServer
app = MCPServer(
"My Server",
instructions="MCP Server for project management",
)
Tímy pracujúce v JavaScripte a TypeScripte majú k dispozícii oficiálne MCP SDK vydané spoločnosťou Anthropic. Logika je porovnateľná, hoci sa syntax líši:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({
name: "My Server",
version: "1.0.0",
});
Voľba závisí menej od schopností a viac od ekosystému, z ktorého bude server čerpať dáta. Server, ktorý dopytuje databázu cez SQLAlchemy alebo znovu používa existujúce spracovateľské skripty, bude prirodzene v Pythone; server založený na existujúcej aplikácii Express zostane v TypeScripte. Nasledujúca tabuľka sumarizuje praktické rozdiely.
| Kritérium | MCPServer (Python SDK) | MCP SDK (TypeScript) |
|---|---|---|
| Zrelosť | Veľmi zrelé | Zrelé |
| Dekorátory | @app.tool() | Metóda server.tool() |
| HTTP Transport | Vstavaný (FastAPI) | Vstavaný (Express) |
| Komunita | Veľká | Veľká |
Štruktúra projektu, ktorá vydrží
Odporúčaná štruktúra adresárov oddeľuje štyri zodpovednosti: čo vidí model (tools/), čo pristupuje k dátam (services/), čo riadi prístup (auth/) a čo opisuje prostredie (config.py, .env).
my-mcp-server/
├── server.py # Vstupný bod FastAPI + pripojenie MCP
├── tools/
│ ├── __init__.py
│ ├── project_tools.py # Nástroje na správu projektov
│ ├── file_tools.py # Nástroje na správu súborov
│ └── search_tools.py # Nástroje na vyhľadávanie
├── services/
│ ├── __init__.py
│ ├── database.py # Prístup k databáze
│ └── external_api.py # Volania externých API
├── auth/
│ ├── __init__.py
│ └── middleware.py # Autentifikačný middleware
├── config.py # Konfigurácia (premenné prostredia)
├── Dockerfile # Kontajnerizácia
├── requirements.txt # Python závislosti
├── .env # Premenné prostredia (neodosielajú sa do repozitára)
└── tests/
├── test_tools.py
└── test_integration.py
Toto oddelenie má priamy, konkrétny dôsledok: tvoje nástroje už neobsahujú SQL ani HTTP volania, iba validáciu a delegovanie na službu. Business logiku potom môžeš testovať bez prechodu cez MCP a meniť databázy bez toho, aby si sa dotkol jediného docstringu, ktorý vidí model.
Vstupný bod: server.py
Hlavný súbor nerobí nič iné, len zostavuje komponenty: vytvára aplikáciu FastAPI, skladá middleware a pripája každý MCP server na jeho vlastnú cestu.
# server.py
"""Vstupný bod MCP servera."""
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
# Každý MCP server musí spustiť svojho správcu relácií
@asynccontextmanager
async def lifespan(app: FastAPI):
async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
yield
# Aplikácia FastAPI
api = FastAPI(
title="My MCP Server",
version="1.0.0",
lifespan=lifespan,
)
# CORS pre webových klientov
api.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)
# Autentifikačný middleware
api.add_middleware(AuthMiddleware)
# Verejný hostname, pod ktorým sú servery poskytované (inak: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])
# Pripojenie MCP serverov na odlišné cesty
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))
# Domovská stránka (voliteľné, ale užitočné)
@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)
Pripojenie na odlišné cesty umožňuje používateľom povoliť iba doménu, ktorú potrebujú: niekto, kto hľadá dokumentáciu, sa pripojí na /search/mcp, bez toho aby mu boli ponúkané nástroje na správu projektov. Čo sa týka domovskej stránky, zdá sa byť triviálna, kým sa kolega neopýta na presnú URL koncového bodu; odpovie za teba a slúži ako kontrola zdravotného stavu.
Jeden modul nástrojov na doménu
Každý súbor v priečinku tools/ deklaruje svoj vlastný objekt MCPServer a zoskupuje nástroje z rovnakej funkčnej domény. Takto vyzerá modul správy projektov, ktorý bol predtým importovaný v server.py:
# tools/project_tools.py
"""MCP nástroje na správu projektov."""
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:
"""Vytvorí nový projekt.
Args:
name: Názov projektu (2-100 znakov)
description: Popis projektu (voliteľné)
Returns:
JSON s detailmi vytvoreného projektu
"""
project = await db.projects.create(name=name, description=description)
return project.to_json()
@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
"""Zoznam projektov podľa stavu.
Args:
status: Filter podľa stavu: active, archived, all (predvolené: active)
Returns:
JSON so zoznamom projektov
"""
projects = await db.projects.list(status=status)
return projects.to_json()
Všimni si, aké krátke sú telá funkcií: len dva riadky každá, pretože prístup k dátam žije v services/database.py. Nástroj iba opisuje svoju zmluvu modelu a deleguje prácu.
Centralizovaná konfigurácia
Akákoľvek hodnota, ktorá sa mení medzi tvojím strojom a produkčným serverom, musí pochádzať z prostredia, nikdy z kódu. Jediný súbor config.py zhromažďuje tieto premenné spolu s ich predvolenými hodnotami:
# config.py
"""Konfigurácia MCP servera."""
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()
Parameter max_results ilustruje výhodu tohto prístupu: v deň, keď nástroj vráti príliš veľa výsledkov a zaplaví kontext modelu, upravíš premennú prostredia a reštartuješ službu bez opätovného nasadenia kódu.
Chyby, ktorým model rozumie
Výnimka v Pythone, ktorá náhle prebublá nahor, modelu nič nepovie: vidí zlyhanie, ale nechápe prečo, a často sa pokúsi o to isté znova. Namiesto toho štandardizuj explicitný formát odpovede pri chybe s kódom a správou.
import json
def error_response(message: str, code: str = "error") -> str:
"""Formátuje štandardizovanú chybovú správu."""
return json.dumps({
"success": False,
"error": {"code": code, "message": message}
}, ensure_ascii=False)
@project_mcp.tool()
async def get_project(project_id: str) -> str:
"""Získa detaily projektu podľa 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")
Rozdiel je v konverzácii rozhodujúci. Ak model dostane not_found, pochopí, že musí najprv vypísať zoznam projektov, aby našiel správne ID; ak narazí na tichú výnimku, vzdá to alebo sa dostane do slučky.
Stavový alebo bezstavový
Stavový server si uchováva informácie medzi volaniami: databáza v pamäti, relácie používateľov, kontext práce. Toto je bežné pre manažérske servery, ako bol správca úloh z predchádzajúcej lekcie. Bezstavový server spracováva každú požiadavku nezávisle a nič si nepamätá – odporúča sa pre čisté výpočty alebo transformácie a umožňuje horizontálne škálovanie, keďže ktorákoľvek inštancia môže vybaviť ktorúkoľvek požiadavku. SDK v2 to umožňuje pomocou parametra HTTP aplikácie (už sa neposiela do konštruktora). Všimni si, že so špecifikáciou z 28. 7. 2026 protokol sám o sebe už nepozná relácie: toto nastavenie sa týka len klientov vyjednávajúcich staršiu verziu protokolu.
app = MCPServer("Stateless Server")
# Nastavenie sa odovzdáva pri vytváraní HTTP aplikácie
mcp_app = app.streamable_http_app(stateless_http=True)
Túto otázku sa rozhodni skôr, než napíšeš svoje nástroje, nie až potom: prechod zo stavového na bezstavový server znamená presun všetkého stavu do externej databázy, čo prepíše dobrú časť kódu.
Kľúčové poznatky
- Rozdeľ svoje nástroje do tematických modulov v priečinku
tools/ - Použi FastAPI ako HTTP základ, pripoj MCP servery na vyhradené cesty a odovzdaj im ich životný cyklus (lifespan)
- Centralizuj konfiguráciu cez premenné prostredia
- Štandardizuj formáty odpovedí pri chybách, aby ich model vedel využiť
- Vyber si medzi stavovým (správa dát) a bezstavovým (čisté výpočty)
- Pridaj domovskú stránku
/na zdokumentovanie svojich MCP koncových bodov