Arkitektur for en brugerdefineret MCP-server
På denne side
Opdateret 2. november 2026 — MCP Python SDK v2. Dette kursus følger nu version 2 af
mcp-SDK’et (2.3.0 pr. 2. oktober 2026):MCPServererstatterFastMCP, transportindstillinger flyttes tilrun()ellerstreamable_http_app(), og en applikation, der eksponeres under et rigtigt værtsnavn, skal deklarere dette værtsnavn (transport_security). Dette er også den version, der kræves af Mistral SDK:mistralai[agents]-ekstraktionen krævermcp>=2.2.0,<3.0. Kilder: Hvad er nyt i v2 · Migrationsguide · Deploy & scale.
Design af en produktionsklar MCP-server
En MCP-prototype kan ofte klares i en fil på fyrre linjer, og det er tit nok til at overbevise et team. Men når du skal i gang med rigtig brug, ændrer alt sig: flere personer kalder på serveren, antallet af værktøjer vokser, konfigurationen varierer mellem miljøer, og den enkelte fil bliver umulig at vedligeholde. Denne lektion dækker de arkitektoniske beslutninger, der forhindrer, at du løber ind i denne murvalg af framework, strukturering af dit projekt, håndtering af konfiguration og fejl samt valget mellem stateful og stateless servere.
Valg af framework
I Python er klassen MCPServer fra det officielle SDK (tidligere FastMCP) standardværktøjet. Den eksponerer et decorator-baseret API og håndterer MCP-protokollen for dig, så en server bliver levende på tre linjer:
from mcp.server.mcpserver import MCPServer
app = MCPServer(
"My Server",
instructions="MCP Server for project management",
)
JavaScript- og TypeScript-teams har det officielle MCP-SDK udgivet af Anthropic. Logikken er sammenlignelig, selvom syntaksen er anderledes:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({
name: "My Server",
version: "1.0.0",
});
Valget afhænger mindre af kapaciteter og mere af det økosystem, hvor din server skal hente sine data. En server, der spørger en database via SQLAlchemy eller genbruger eksisterende behandlingsscripts, vil naturligt være skrevet i Python; en server, der hviler på en eksisterende Express-applikation, vil forblive i TypeScript. Tabellen nedenfor opsummerer de praktiske forskelle.
| Kriterium | MCPServer (Python SDK) | MCP SDK (TypeScript) |
|---|---|---|
| Modenhed | Meget moden | Moden |
| Decorators | @app.tool() | server.tool()-metode |
| HTTP-transport | Indbygget (FastAPI) | Indbygget (Express) |
| Fællesskab | Stort | Stort |
En projektstruktur, der holder
Den anbefalede mappestruktur adskiller fire ansvarsområder: hvad modellen ser (tools/), hvad der tilgår data (services/), hvad der styrer adgang (auth/), og hvad der beskriver miljøet (config.py, .env).
my-mcp-server/
├── server.py # FastAPI-entry point + MCP-montering
├── tools/
│ ├── __init__.py
│ ├── project_tools.py # Værktøjer til projektstyring
│ ├── file_tools.py # Værktøjer til filhåndtering
│ └── search_tools.py # Søgeværktøjer
├── services/
│ ├── __init__.py
│ ├── database.py # Databaseadgang
│ └── external_api.py # Eksterne API-kald
├── auth/
│ ├── __init__.py
│ └── middleware.py # Autentificeringsmiddleware
├── config.py # Konfiguration (miljøvariabler)
├── Dockerfile # Containerisering
├── requirements.txt # Python-afhængigheder
├── .env # Miljøvariabler (ikke commit'et)
└── tests/
├── test_tools.py
└── test_integration.py
Denne opdeling har en direkte, konkret konsekvens: dine værktøjer indeholder ikke længere SQL eller HTTP-kald, kun validering og delegering til en service. Du kan derefter teste forretningslogik uden om MCP og skifte database uden at røre en eneste docstring, som modellen ser.
Entry point: server.py
Hovedfilen gør intet andet end at samle komponenter: den opretter FastAPI-applikationen, stabler middleware og monterer hver MCP-server på sin egen rute.
# server.py
"""MCP server entry point."""
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
# Hver MCP-server skal starte sin sessionsmanager
@asynccontextmanager
async def lifespan(app: FastAPI):
async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
yield
# FastAPI-applikation
api = FastAPI(
title="My MCP Server",
version="1.0.0",
lifespan=lifespan,
)
# CORS til webklienter
api.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)
# Autentificeringsmiddleware
api.add_middleware(AuthMiddleware)
# Offentligt værtsnavn, som servere betjenes under (ellers: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])
# Monter MCP-servere på forskellige ruter
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))
# Hjemmeside (valgfri, men nyttig)
@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)
Montering på forskellige ruter lader brugere aktivere præcis det domæne, de har brug for: nogen, der søger dokumentation, forbinder til /search/mcp uden at få tilbudt projektstyringsværktøjer. Hvad angår hjemmesiden, virker den triviel, indtil en kollega spørger efter den nøjagtige endpoint-URL; den svarer for dig og fungerer som et health check.
Ét værktøjsmodul per domæne
Hver fil i mappen tools/ deklarerer sit eget MCPServer-objekt og grupperer værktøjer fra samme funktionelle domæne. Sådan ser projektstyringsmodulet ud, som tidligere blev importeret af server.py:
# tools/project_tools.py
"""MCP tools for project management."""
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:
"""Creates a new project.
Args:
name: Project name (2-100 characters)
description: Project description (optional)
Returns:
JSON with created project details
"""
project = await db.projects.create(name=name, description=description)
return project.to_json()
@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
"""Lists projects by status.
Args:
status: Filter by status: active, archived, all (default: active)
Returns:
JSON with list of projects
"""
projects = await db.projects.list(status=status)
return projects.to_json()
Læg mærke til, hvor korte funktionskroppene er: kun to linjer hver, fordi dataadgang lever i services/database.py. Værktøjet beskriver blot sin kontrakt over for modellen og delegerer.
Centraliseret konfiguration
Enhver værdi, der ændrer sig mellem din maskine og produktionsserveren, skal komme fra miljøet, aldrig fra koden. En enkelt fil config.py samler disse variabler med deres standardværdier:
# config.py
"""MCP server configuration."""
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()
Parameteren max_results illustrerer fordelen ved denne tilgang: den dag et værktøj returnerer for mange resultater og mætter modellens kontekst, justerer du en miljøvariabel og genstarter uden at skulle redeploye kode.
Fejl, som modellen kan læse
En Python-undtagelse, der bobler abrupt op, fortæller modellen ingenting: den ser en fejl uden at forstå hvorfor, og forsøger ofte identisk igen. Standardiser i stedet et eksplicit fejlresponsformat med en kode og en besked.
import json
def error_response(message: str, code: str = "error") -> str:
"""Formats a standardized error message."""
return json.dumps({
"success": False,
"error": {"code": code, "message": message}
}, ensure_ascii=False)
@project_mcp.tool()
async def get_project(project_id: str) -> str:
"""Retrieves project details by 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")
Forskellen er afgørende i samtalen. Mødt med not_found forstår modellen, at den først skal liste projekter for at finde det rigtige ID; mødt med en tavs undtagelse giver den op eller havner i en løkke.
Stateful eller stateless
En stateful server beholder information mellem kald: in-memory database, brugersessioner, arbejdskontekst. Dette er almindeligt for styringsservere, som opgavehåndteringen fra den forrige lektion. En stateless server håndterer hver anmodning uafhængigt og husker ingenting – anbefalet til ren beregning eller transformation og muliggør horisontal skalering, da enhver instans kan håndtere enhver anmodning. SDK v2 muliggør dette med en HTTP-applikationsparameter (ikke længere sendt til konstruktøren). Bemærk, at med specifikationen fra 2026-07-28 kender protokollen selv ikke længere sessioner: denne indstilling vedrører kun klienter, der forhandler en tidligere protokolversion.
app = MCPServer("Stateless Server")
# Indstillingen sendes, når HTTP-applikationen bygges
mcp_app = app.streamable_http_app(stateless_http=True)
Beslut dette spørgsmål, før du skriver dine værktøjer, ikke bagefter: at flytte fra en stateful til en stateless server betyder at flytte al tilstand til en ekstern database, hvilket omskriver en god del af koden.
Vigtige pointer
- Adskil dine værktøjer i tematiske moduler i en mappe
tools/ - Brug FastAPI som HTTP-basis, monter MCP-servere på dedikerede ruter, og send deres lifespan
- Centraliser konfiguration via miljøvariabler
- Standardiser formater for fejlrespons, så modellen kan bruge dem
- Vælg mellem stateful (datahåndtering) og stateless (ren beregning)
- Tilføj en
/-hjemmeside for at dokumentere dine MCP-endpoints