Architektura niestandardowego serwera MCP
Na tej stronie
Zaktualizowano 2 listopada 2026 — MCP Python SDK v2. Kurs opiera się teraz na wersji 2 SDK
mcp(2.3.0 według stanu na 2 października 2026):MCPServerzastępujeFastMCP, ustawienia transportu przeniesiono do metodrun()lubstreamable_http_app(), a aplikacja wystawiona pod rzeczywistą nazwą hosta musi ją zadeklarować (transport_security). Jest to również wersja wymagana przez Mistral SDK: dodatkowy pakietmistralai[agents]wymagamcp>=2.2.0,<3.0. Źródła: Co nowego w v2 · Przewodnik migracyjny · Wdrażanie i skalowanie.
Projektowanie produkcyjnego serwera MCP
Prototyp MCP mieści się w pliku liczącym czterdzieści linii i często wystarcza, by przekonać zespół. Przejście do użytku rzeczywistego zmienia wszystko: z serwera korzysta wiele osób, przybywa narzędzi, konfiguracja różni się w zależności od środowiska, a pojedynczy plik staje się niemożliwy do utrzymania. Ta lekcja omawia decyzje architektoniczne, które pozwalają uniknąć tego muru – wybór frameworka, strukturyzację projektu, zarządzanie konfiguracją i błędami oraz wybór między serwerami stanowymi a bezstanowymi.
Wybór frameworka
W Pythonie standardowym narzędziem jest klasa MCPServer z oficjalnego SDK (dawniej FastMCP). Udostępnia ona API oparte na dekoratorach i obsługuje protokół MCP za Ciebie, dzięki czemu serwer ożywa w trzech liniach kodu:
from mcp.server.mcpserver import MCPServer
app = MCPServer(
"My Server",
instructions="MCP Server for project management",
)
Zespoły pracujące w JavaScript i TypeScript mają do dyspozycji oficjalne MCP SDK wydane przez Anthropic. Logika jest porównywalna, choć składnia się różni:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({
name: "My Server",
version: "1.0.0",
});
Wybór zależy mniej od możliwości, a bardziej od ekosystemu, z którego serwer będzie pobierał dane. Serwer odpytujący bazę danych przez SQLAlchemy lub wykorzystujący istniejące skrypty przetwarzające naturalnie powstanie w Pythonie; serwer oparty na istniejącej aplikacji Express pozostanie w TypeScript. Poniższa tabela podsumowuje praktyczne różnice.
| Kryterium | MCPServer (Python SDK) | MCP SDK (TypeScript) |
|---|---|---|
| Dojrzałość | Bardzo duża | Duża |
| Dekoratory | @app.tool() | Metoda server.tool() |
| Transport HTTP | Wbudowany (FastAPI) | Wbudowany (Express) |
| Społeczność | Duża | Duża |
Struktura projektu na lata
Zalecana struktura katalogów rozdziela cztery obszary odpowiedzialności: to, co widzi model (tools/), to, co uzyskuje dostęp do danych (services/), to, co kontroluje dostęp (auth/), oraz to, co opisuje środowisko (config.py, .env).
my-mcp-server/
├── server.py # Punkt wejścia FastAPI + montowanie MCP
├── tools/
│ ├── __init__.py
│ ├── project_tools.py # Narzędzia do zarządzania projektami
│ ├── file_tools.py # Narzędzia do zarządzania plikami
│ └── search_tools.py # Narzędzia wyszukiwania
├── services/
│ ├── __init__.py
│ ├── database.py # Dostęp do bazy danych
│ └── external_api.py # Wywołania zewnętrznych API
├── auth/
│ ├── __init__.py
│ └── middleware.py # Middleware uwierzytelniający
├── config.py # Konfiguracja (zmienne środowiskowe)
├── Dockerfile # Konteneryzacja
├── requirements.txt # Zależności Pythona
├── .env # Zmienne środowiskowe (nie commitowane)
└── tests/
├── test_tools.py
└── test_integration.py
Ten podział ma bezpośredni, konkretny skutek: Twoje narzędzia nie zawierają już zapytań SQL ani wywołań HTTP, jedynie walidację i delegowanie zadań do warstwy usług. Możesz wtedy testować logikę biznesową z pominięciem MCP i zmieniać bazy danych bez dotykania choćby jednego docstringa widocznego dla modelu.
Punkt wejścia: server.py
Główny plik robi tylko jedno: assembleuje komponenty. Tworzy aplikację FastAPI, nakłada middleware’y i montuje każdy serwer MCP na osobnej ścieżce.
# server.py
"""Punkt wejścia serwera 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
# Każdy serwer MCP musi uruchomić swój menedżer sesji
@asynccontextmanager
async def lifespan(app: FastAPI):
async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
yield
# Aplikacja FastAPI
api = FastAPI(
title="My MCP Server",
version="1.0.0",
lifespan=lifespan,
)
# CORS dla klientów webowych
api.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)
# Middleware uwierzytelniający
api.add_middleware(AuthMiddleware)
# Publiczny host, pod którym serwery są udostępniane (w przeciwnym razie: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])
# Montowanie serwerów MCP na osobnych ścieżkach
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))
# Strona główna (opcjonalna, ale przydatna)
@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)
Montowanie na osobnych ścieżkach pozwala użytkownikom włączać tylko potrzebną im domenę: ktoś szukający dokumentacji łączy się z /search/mcp, nie otrzymując oferty narzędzi do zarządzania projektami. Co do strony głównej – wydaje się trywialna, dopóki kolega nie zapyta o dokładny URL punktu końcowego; odpowiada za Ciebie i służy jako sprawdzenie zdrowia usługi.
Jeden moduł narzędzi na domenę
Każdy plik w folderze tools/ deklaruje własny obiekt MCPServer i grupuje narzędzia z tej samej domeny funkcjonalnej. Oto jak wygląda moduł zarządzania projektami, importowany wcześniej przez server.py:
# tools/project_tools.py
"""Narzędzia MCP do zarządzania projektami."""
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:
"""Tworzy nowy projekt.
Args:
name: Nazwa projektu (2-100 znaków)
description: Opis projektu (opcjonalnie)
Returns:
JSON ze szczegółami utworzonego 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:
"""Wyświetla listę projektów według statusu.
Args:
status: Filtrowanie według statusu: active, archived, all (domyślnie: active)
Returns:
JSON z listą projektów
"""
projects = await db.projects.list(status=status)
return projects.to_json()
Zauważ, jak krótkie są ciała funkcji: zaledwie dwie linie każda, ponieważ dostęp do danych żyje w services/database.py. Narzędzie jedynie opisuje modelowi swoją umowę i deleguje zadanie.
scentralizowana konfiguracja
Każda wartość zmieniająca się między Twoją maszyną a serwerem produkcyjnym musi pochodzić ze środowiska, nigdy z kodu. Pojedynczy plik config.py zbiera te zmienne wraz z ich wartościami domyślnymi:
# config.py
"""Konfiguracja serwera 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()
Parametr max_results ilustruje korzyść z tego podejścia: dnia, w którym narzędzie zwróci zbyt wiele wyników i zapcha kontekst modelu, dostosowujesz zmienną środowiskową i restartujesz usługę bez konieczności ponownego wdrażania kodu.
Błędy czytelne dla modelu
Wyjątek Pythona, który nagle вспłynie na powierzchnię, nic nie mówi modelowi: widzi on awarię, nie rozumiejąc przyczyny, i często podejmuje identyczną próbę ponownie. Zamiast tego ustandaryzuj jawny format odpowiedzi błędu z kodem i komunikatem.
import json
def error_response(message: str, code: str = "error") -> str:
"""Formatuje ustandaryzowany komunikat błędu."""
return json.dumps({
"success": False,
"error": {"code": code, "message": message}
}, ensure_ascii=False)
@project_mcp.tool()
async def get_project(project_id: str) -> str:
"""Pobiera szczegóły projektu po 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")
Różnica jest decydująca w rozmowie. W obliczu not_found model rozumie, że musi najpierw wyświetlić listę projektów, by znaleźć właściwe ID; w obliczu cichego wyjątku poddaje się lub wpada w pętlę.
Stanowy czy bezstanowy
Serwer stanowy (stateful) przechowuje informacje między wywołaniami: baza danych w pamięci, sesje użytkowników, kontekst pracy. Jest to powszechne w serwerach zarządczych, takich jak menedżer zadań z poprzedniej lekcji. Serwer bezstanowy (stateless) obsługuje każde żądanie niezależnie, niczego nie pamiętając – zalecany do czystych obliczeń lub transformacji, pozwalający na skalowanie poziome, ponieważ любая instancja może obsłużyć każde żądanie. SDK v2 umożliwia to poprzez parametr aplikacji HTTP (nie przekazywany już do konstruktora). Pamiętaj, że zgodnie ze specyfikacją z 2026-07-28 sam protokół nie zna już sesji: ustawienie to dotyczy jedynie klientów negocjujących wcześniejszą wersję protokołu.
app = MCPServer("Stateless Server")
# Ustawienie przekazywane jest podczas budowania aplikacji HTTP
mcp_app = app.streamable_http_app(stateless_http=True)
Zdecyduj o tej kwestii przed napisaniem narzędzi, a nie po: przejście z serwera stanowego na bezstanowy oznacza przeniesienie całego stanu do zewnętrznej bazy danych, co przepisuje sporą część kodu.
Kluczowe wnioski
- Rozdziel swoje narzędzia na moduły tematyczne w folderze
tools/ - Użyj FastAPI jako bazy HTTP, zamontuj serwery MCP na dedykowanych ścieżkach i przekaż ich cykl życia (lifespan)
- scentralizuj konfigurację poprzez zmienne środowiskowe
- Ustandaryzuj formaty odpowiedzi błędów, aby model mógł z nich korzystać
- Wybierz między trybem stanowym (zarządzanie danymi) a bezstanowym (czyste obliczenia)
- Dodaj stronę główną
/, aby udokumentować swoje punkty końcowe MCP