Arhitektura prilagojenega strežnika MCP
Na tej strani
Posodobljeno 2. novembra 2026 — MCP Python SDK v2. Ta tečaj zdaj sledi različici 2 paketa SDK
mcp(2.3.0 z dne 2. oktobra 2026):MCPServernadomeščaFastMCP, nastavitve prenosa se premaknejo vrun()alistreamable_http_app(), aplikacija, ki je izpostavljena pod pravim imenom gostitelja, pa mora to ime gostitelja deklarirati (transport_security). To je tudi različica, ki jo zahteva Mistral SDK: dodatekmistralai[agents]zahtevamcp>=2.2.0,<3.0. Viri: Kaj je novega v v2 · Vodnik za selitev · Namestitev in skaliranje.
Načrtovanje produkcijskega strežnika MCP
Prototip MCP se prilega v datoteko s štiridesetimi vrsticami in to je pogosto dovolj, da prepričaš ekipo. Prehod na realno uporabo pa vse spremeni: strežnik kliče več ljudi, orodja se množijo, konfiguracija se razlikuje med okolji in ena sama datoteka postane neobvladljiva. Ta lekcija pokriva arhitekturne odločitve, ki preprečujejo trk ob ta zid – izbiro ogrodja, strukturiranje projekta, upravljanje konfiguracije in napak ter odločitev med strežniki s stanjem in brez njega.
Izbira tvojega ogrodja
V Pythonu je razred MCPServer iz uradnega SDK (prej FastMCP) standardno orodje. Izpostavlja API, ki temelji na dekoraterjih, in namesto tebe obravnava protokol MCP, tako da strežnik oživi v treh vrsticah:
from mcp.server.mcpserver import MCPServer
app = MCPServer(
"My Server",
instructions="MCP Server for project management",
)
Ekipam, ki uporabljajo JavaScript in TypeScript, je na voljo uradni MCP SDK, ki ga objavlja Anthropic. Logika je primerljiva, čeprav se sintaksa razlikuje:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({
name: "My Server",
version: "1.0.0",
});
Izbira je manj odvisna od zmogljivosti in bolj od ekosistema, v katerem bo tvoj strežnik pridobival podatke. Strežnik, ki poizveduje v bazo podatkov prek SQLAlchemy ali ponovno uporablja obstoječe skripte za obdelavo, bo naravno napisan v Pythonu; strežnik, ki temelji na obstoječi aplikaciji Express, bo ostal v TypeScriptu. Spodnja tabela povzema praktične razlike.
| Merilo | MCPServer (Python SDK) | MCP SDK (TypeScript) |
|---|---|---|
| Zrelost | Zelo zrelo | Zrelo |
| Dekoraterji | @app.tool() | Metoda server.tool() |
| HTTP prenos | Vgrajen (FastAPI) | Vgrajen (Express) |
| Skupnost | Velika | Velika |
Struktura projekta, ki zdrži čas
Priporočena struktura imenika ločuje štiri odgovornosti: kaj vidi model (tools/), kaj dostopa do podatkov (services/), kaj nadzira dostop (auth/) in kaj opisuje okolje (config.py, .env).
my-mcp-server/
├── server.py # Vstopna točka FastAPI + namestitev MCP
├── tools/
│ ├── __init__.py
│ ├── project_tools.py # Orodja za upravljanje projektov
│ ├── file_tools.py # Orodja za upravljanje datotek
│ └── search_tools.py # Orodja za iskanje
├── services/
│ ├── __init__.py
│ ├── database.py # Dostop do baze podatkov
│ └── external_api.py # Klici zunanjih API-jev
├── auth/
│ ├── __init__.py
│ └── middleware.py # Vmesna programska oprema za avtentikacijo
├── config.py # Konfiguracija (spremenljivke okolja)
├── Dockerfile # Kontejnerizacija
├── requirements.txt # Odvisnosti Python
├── .env # Spremenljivke okolja (ne v repozitoriju)
└── tests/
├── test_tools.py
└── test_integration.py
Ta ločitev ima neposredno, konkretno posledico: tvoja orodja ne vsebujejo več klicev SQL ali HTTP, temveč le validacijo in delegiranje storitvi. Poslovno logiko lahko nato testiraš brez posredovanja MCP in zamenjaš bazo podatkov, ne da bi se dotaknil enega samega docstringa, ki ga vidi model.
Vstopna točka: server.py
Glavna datoteka ne počne nič drugega, kot da sestavi komponente: ustvari aplikacijo FastAPI, doda vmesno programsko opremo (middleware) in namesti vsak strežnik MCP na svojo pot.
# server.py
"""Vstopna točka strežnika 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
# Vsak strežnik MCP mora zagnati svoj upravitelj sej
@asynccontextmanager
async def lifespan(app: FastAPI):
async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
yield
# Aplikacija FastAPI
api = FastAPI(
title="My MCP Server",
version="1.0.0",
lifespan=lifespan,
)
# CORS za spletne odjemalce
api.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)
# Vmesna programska oprema za avtentikacijo
api.add_middleware(AuthMiddleware)
# Javno ime gostitelja, pod katerim so strežniki na voljo (sicer: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])
# Namestitev strežnikov MCP na ločene poti
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))
# Domača stran (izbirno, a uporabno)
@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)
Namestitev na ločene poti uporabnikom omogoča, da omogočijo le domeno, ki jo potrebujejo: nekdo, ki išče dokumentacijo, se poveže na /search/mcp, ne da bi mu bila ponujena orodja za upravljanje projektov. Kar zadeva domačo stran, se zdi trivialna, dokler te kolega ne vpraša za točen URL končne točke; odgovori namesto tebe in služi kot preverjanje zdravja.
En modul orodij na domeno
Vsaka datoteka v mapi tools/ deklarira svoj objekt MCPServer in združuje orodja iz iste funkcionalne domene. Tako izgleda modul za upravljanje projektov, ki ga je server.py uvozil prej:
# tools/project_tools.py
"""Orodja MCP za upravljanje 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:
"""Ustvari nov projekt.
Args:
name: Ime projekta (2–100 znakov)
description: Opis projekta (izbirno)
Returns:
JSON s podrobnostmi ustvarjenega projekta
"""
project = await db.projects.create(name=name, description=description)
return project.to_json()
@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
"""Izpiše projekte po statusu.
Args:
status: Filtriraj po statusu: active, archived, all (privzeto: active)
Returns:
JSON s seznamom projektov
"""
projects = await db.projects.list(status=status)
return projects.to_json()
Opazi, kako kratka so telesa funkcij: le dve vrstici vsaka, ker dostop do podatkov živi v services/database.py. Orodje modelu preprosto opiše svojo pogodbo in delegira nalogo.
Centralizirana konfiguracija
Vsaka vrednost, ki se spreminja med tvojim računalnikom in produkcijskim strežnikom, mora prihajati iz okolja, nikoli iz kode. Enojna datoteka config.py zbere te spremenljivke z njihovimi privzetimi vrednostmi:
# config.py
"""Konfiguracija strežnika 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()
Parameter max_results ponazarja prednost tega pristopa: dan, ko orodje vrne preveč rezultatov in zasiči kontekst modela, prilagodiš spremenljivko okolja in ponovno zaženeš, ne da bi ponovno namestil kodo.
Napake, ki jih model lahko prebere
Izjema Python, ki nenadoma pricurlja navzgor, modelu ne pove ničesar: vidi napako, ne razume pa zakaj, in pogosto poskusi znova na enak način. Namesto tega standardiziraj ekspliciten format odgovora napake s kodo in sporočilom.
import json
def error_response(message: str, code: str = "error") -> str:
"""Oblikuje standardizirano sporočilo o napaki."""
return json.dumps({
"success": False,
"error": {"code": code, "message": message}
}, ensure_ascii=False)
@project_mcp.tool()
async def get_project(project_id: str) -> str:
"""Pridobi podrobnosti projekta po ID-ju."""
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")
Razlika je v pogovoru odločilna. Ko se sooči z not_found, model razume, da mora najprej izpisati projekte, da najde pravi ID; ko se sooči s tiho izjemo, obupa ali zavrti v zanko.
S stanjem ali brez njega
Strežnik s stanjem (stateful) ohranja informacije med klici: baza podatkov v pomnilniku, uporabniške seje, kontekst dela. To je običajno za strežnike za upravljanje, kot je upravitelj opravil iz prejšnje lekcije. Strežnik brez stanja (stateless) obravnava vsako zahtevo neodvisno in si ne zapomni ničesar – priporočljivo za čisto računanje ali transformacijo ter omogoča vodoravno skaliranje, saj lahko kateri koli primerek obravnava katero koli zahtevo. SDK v2 to omogoča s parametrom HTTP aplikacije (ki se ga ne posreduje več konstruktorju). Upoštevaj, da s specifikacijo z dne 28. 7. 2026 protokol sam po sebi ne pozna več sej: ta nastavitev zadeva le odjemalce, ki pogajajo starejšo različico protokola.
app = MCPServer("Stateless Server")
# Nastavitev se posreduje pri gradnji HTTP aplikacije
mcp_app = app.streamable_http_app(stateless_http=True)
To vprašanje se odloči pred pisanjem orodij, ne po njih: prehod s strežnika s stanjem na strežnik brez stanja pomeni premik vsega stanja v zunanjo bazo podatkov, kar prepisuje dober del kode.
Ključne ugotovitve
- Loči svoja orodja v tematske module v mapi
tools/ - Uporabi FastAPI kot HTTP osnovo, namesti strežnike MCP na namenske poti in jim posreduj njihov življenjski cikel (lifespan)
- Centraliziraj konfiguracijo prek spremenljivk okolja
- Standardiziraj formate odgovorov napak, da jih model lahko uporabi
- Izberi med s stanjem (upravljanje podatkov) in brez stanja (čisto računanje)
- Dodaj domačo stran
/za dokumentacijo svojih končnih točk MCP