Przejdź do głównej treści
Polski— Wybierz język
Menu

Architektura niestandardowego serwera MCP

Lekcja 10 z 14 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Projektowanie produkcyjnego serwera MCP
  2. Wybór frameworka
  3. Struktura projektu na lata
  4. Punkt wejścia: server.py
  5. Jeden moduł narzędzi na domenę
  6. scentralizowana konfiguracja
  7. Błędy czytelne dla modelu
  8. Stanowy czy bezstanowy
  9. Kluczowe wnioski

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): MCPServer zastępuje FastMCP, ustawienia transportu przeniesiono do metod run() lub streamable_http_app(), a aplikacja wystawiona pod rzeczywistą nazwą hosta musi ją zadeklarować (transport_security). Jest to również wersja wymagana przez Mistral SDK: dodatkowy pakiet mistralai[agents] wymaga mcp>=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.

KryteriumMCPServer (Python SDK)MCP SDK (TypeScript)
DojrzałośćBardzo dużaDuża
Dekoratory@app.tool()Metoda server.tool()
Transport HTTPWbudowany (FastAPI)Wbudowany (Express)
SpołecznośćDużaDuż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