Architektura vlastního MCP serveru
Na této stránce
Aktualizováno 2. listopadu 2026 — MCP Python SDK v2. Tento kurz nyní vychází z verze 2 SDK
mcp(konkrétně 2.3.0 k 2. říjnu 2026):MCPServernahrazujeFastMCP, nastavení transportu se přesouvá do metodrun()nebostreamable_http_app()a aplikace vystavená pod skutečným hostname musí tento hostname deklarovat (transport_security). Toto je také verze požadovaná Mistral SDK: extra balíčekmistralai[agents]vyžadujemcp>=2.2.0,<3.0. Zdroje: Co je nového ve v2 · Průvodce migrací · Nasazení a škálování.
Návrh produkčního MCP serveru
Prototyp MCP se vejde do souboru o čtyřiceti řádcích a to často stačí k přesvědčení týmu. Přechod na reálné použití však mění vše: server volá více lidí, nástrojů přibývá, konfigurace se liší podle prostředí a jediný soubor se stává neudržitelným. Tato lekce pokrývá architektonická rozhodnutí, která ti pomohou této zdi předejít – výběr frameworku, strukturování projektu, správa konfigurace a chyb a rozhodování mezi stavovými a bezstavovými servery.
Výběr frameworku
V Pythonu je třída MCPServer z oficiálního SDK (dříve FastMCP) standardním nástrojem. Poskytuje API založené na dekorátorech a zpracovává za tebe protokol MCP, takže server ožije na tři řádky:
from mcp.server.mcpserver import MCPServer
app = MCPServer(
"My Server",
instructions="MCP Server for project management",
)
Týmy pracující v JavaScriptu a TypeScriptu mají k dispozici oficiální MCP SDK vydávané společností Anthropic. Logika je srovnatelná, i když se syntaxe liší:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({
name: "My Server",
version: "1.0.0",
});
Volba závisí méně na možnostech a více na ekosystému, ze kterého bude server čerpat data. Server dotazující databázi přes SQLAlchemy nebo znovu využívající existující skripty pro zpracování bude přirozeně v Pythonu; server stojící na existující aplikaci Express zůstane v TypeScriptu. Následující tabulka shrnuje praktické rozdíly.
| Kritérium | MCPServer (Python SDK) | MCP SDK (TypeScript) |
|---|---|---|
| Vyspělost | Velmi vyspělé | Vyspělé |
| Dekorátory | @app.tool() | Metoda server.tool() |
| HTTP Transport | Vestavěný (FastAPI) | Vestavěný (Express) |
| Komunita | Velká | Velká |
Struktura projektu, která vydrží
Doporučená struktura adresářů odděluje čtyři odpovědnosti: co vidí model (tools/), co přistupuje k datům (services/), co řídí přístup (auth/) a co popisuje prostředí (config.py, .env).
my-mcp-server/
├── server.py # Vstupní bod FastAPI + připojení MCP
├── tools/
│ ├── __init__.py
│ ├── project_tools.py # Nástroje pro správu projektů
│ ├── file_tools.py # Nástroje pro správu souborů
│ └── search_tools.py # Nástroje pro vyhledávání
├── services/
│ ├── __init__.py
│ ├── database.py # Přístup k databázi
│ └── external_api.py # Volání externích API
├── auth/
│ ├── __init__.py
│ └── middleware.py # Autentizační middleware
├── config.py # Konfigurace (proměnné prostředí)
├── Dockerfile # Kontejnerizace
├── requirements.txt # Python závislosti
├── .env # Proměnné prostředí (nekomitovat)
└── tests/
├── test_tools.py
└── test_integration.py
Toto oddělení má přímý a konkrétní důsledek: tvé nástroje již neobsahují SQL ani HTTP volání, pouze validaci a delegování na službu. Business logiku pak můžeš testovat bez nutnosti procházet přes MCP a měnit databáze, aniž bys musel sahat na jedinou docstring, kterou vidí model.
Vstupní bod: server.py
Hlavní soubor nedělá nic jiného, než že sestavuje komponenty: vytváří aplikaci FastAPI, skládá middleware a připojuje každý MCP server na jeho vlastní trasu.
# server.py
"""Vstupní bod MCP serveru."""
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í spustit svůj správce relací
@asynccontextmanager
async def lifespan(app: FastAPI):
async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
yield
# Aplikace FastAPI
api = FastAPI(
title="My MCP Server",
version="1.0.0",
lifespan=lifespan,
)
# CORS pro webové klienty
api.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)
# Autentizační middleware
api.add_middleware(AuthMiddleware)
# Veřejný hostname, pod kterým jsou servery obsluhovány (jinak: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])
# Připojení MCP serverů na odlišné trasy
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 (volitelné, ale užiteč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)
Připojení na odlišné trasy umožňuje uživatelům povolit pouze doménu, kterou potřebují: někdo hledající dokumentaci se připojí na /search/mcp, aniž by mu byly nabízeny nástroje pro správu projektů. Co se týče domovské stránky, zdá se být triviální, dokud se kolega nezeptá na přesnou URL koncového bodu; odpoví za tebe a slouží jako kontrola zdraví (health check).
Jeden modul nástrojů na doménu
Každý soubor ve složce tools/ deklaruje vlastní objekt MCPServer a seskupuje nástroje ze stejné funkční domény. Takto vypadá modul pro správu projektů, který byl dříve importován v server.py:
# tools/project_tools.py
"""Nástroje MCP pro správu projektů."""
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:
"""Vytvoří nový projekt.
Args:
name: Název projektu (2–100 znaků)
description: Popis projektu (volitelné)
Returns:
JSON s detaily vytvořené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:
"""Vypíše projekty podle stavu.
Args:
status: Filtr podle stavu: active, archived, all (výchozí: active)
Returns:
JSON se seznamem projektů
"""
projects = await db.projects.list(status=status)
return projects.to_json()
Všimni si, jak stručná jsou těla funkcí: pouze dva řádky, protože přístup k datům žije v services/database.py. Nástroj pouze popisuje svou smlouvu modelu a deleguje práci.
Centralizovaná konfigurace
Jakákoli hodnota, která se liší mezi tvým strojem a produkčním serverem, musí pocházet z prostředí, nikdy z kódu. Jediný soubor config.py shromažďuje tyto proměnné i s jejich výchozími hodnotami:
# config.py
"""Konfigurace MCP serveru."""
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()
Parametr max_results ilustruje výhodu tohoto přístupu: v den, kdy nástroj vrátí příliš mnoho výsledků a zaplní kontext modelu, upravíš proměnnou prostředí a restartuješ službu, aniž bys musel znovu nasazovat kód.
Chyby čitelné pro model
Výjimka v Pythonu, která prudce probublá nahoru, modelu nic neřekne: vidí selhání, ale nechápe proč, a často se pokusí o totéž znovu. Místo toho standardizuj explicitní formát odpovědi při chybě s kódem a zprávou.
import json
def error_response(message: str, code: str = "error") -> str:
"""Formátuje standardizovanou chybovou zprá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:
"""Načte detaily projektu podle 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")
Rozdíl je v konverzaci zásadní. Tváří v tvář not_found model pochopí, že musí nejprve vypsat projekty, aby našel správné ID; tváří v tvář tiché výjimce to vzdá nebo se dostane do smyčky.
Stavový nebo bezstavový
Stavový server si uchovává informace mezi voláními: databáze v paměti, uživatelské relace, kontext práce. To je běžné u serverů pro správu, jako byl správce úkolů z předchozí lekce. Bezstavový server zpracovává každý požadavek nezávisle a nic si nepamatuje – doporučeno pro čisté výpočty nebo transformace a umožňuje horizontální škálování, protože jakákoli instance může zpracovat jakýkoli požadavek. SDK v2 to umožňuje pomocí parametru HTTP aplikace (již se nepředává do konstruktoru). Všimni si, že podle specifikace z 28. 7. 2026 protokol sám o sobě již nezná relace: toto nastavení se týká pouze klientů vyjednávajících starší verzi protokolu.
app = MCPServer("Stateless Server")
# Nastavení se předává při vytváření HTTP aplikace
mcp_app = app.streamable_http_app(stateless_http=True)
Rozhodni se pro tuto otázku před napsáním nástrojů, ne až po nich: přechod ze stavového na bezstavový server znamená přesun veškerého stavu do externí databáze, což přepíše velkou část kódu.
Klíčové poznatky
- Rozděl své nástroje do tematických modulů ve složce
tools/ - Použij FastAPI jako HTTP základ, připoj MCP servery na vyhrazené trasy a předej jim jejich životní cyklus (lifespan)
- Centralizuj konfiguraci prostřednictvím proměnných prostředí
- Standardizuj formáty chybových odpovědí, aby je model mohl využít
- Vyber si mezi stavovým (správa dat) a bezstavovým (čisté výpočty) řešením
- Přidej domovskou stránku
/pro zdokumentování svých koncových bodů MCP