Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Architectuur van een aangepaste MCP-server

Les 10 van 14 Bijgewerkt op 2 november 2026 Ontwikkelaar
Op deze pagina
  1. Het ontwerpen van een productieklaar MCP-server
  2. Uw framework kiezen
  3. Een projectstructuur die standhoudt
  4. Het entry point: server.py
  5. Eén tools-module per domein
  6. Gecentraliseerde configuratie
  7. Fouten die het model kan lezen
  8. Stateful of stateless
  9. Belangrijkste punten

Bijgewerkt op 2 november 2026 — MCP Python SDK v2. Deze cursus volgt nu versie 2 van de mcp-SDK (2.3.0 per 2 oktober 2026): MCPServer vervangt FastMCP, transportinstellingen verhuizen naar run() of streamable_http_app(), en een applicatie die onder een echte hostnaam wordt aangeboden, moet die hostnaam declareren (transport_security). Dit is ook de versie die vereist is door de Mistral SDK: de mistralai[agents]-extra vereist mcp>=2.2.0,<3.0. Bronnen: Wat is nieuw in v2 · Migratiegids · Implementeren & schalen.

Het ontwerpen van een productieklaar MCP-server

Een MCP-prototype past in een bestand van veertig regels, en dat is vaak genoeg om een team te overtuigen. De overstap naar gebruik in de echte wereld verandert echter alles: meerdere personen roepen de server aan, het aantal tools neemt toe, de configuratie verschilt per omgeving, en het enkele bestand wordt ononderhoudbaar. Deze les behandelt de architecturale beslissingen die voorkomen dat u tegen deze muur loopt: het kiezen van een framework, het structureren van uw project, het beheren van configuratie en fouten, en het kiezen tussen stateful en stateless servers.

Uw framework kiezen

In Python is de klasse MCPServer uit de officiële SDK (voorheen FastMCP) de standaardtool. Deze biedt een API op basis van decorators en behandelt het MCP-protocol voor u, zodat een server in drie regels tot leven komt:

from mcp.server.mcpserver import MCPServer

app = MCPServer(
    "My Server",
    instructions="MCP Server for project management",
)

JavaScript- en TypeScript-teams hebben de officiële MCP-SDK die door Anthropic is gepubliceerd. De logica is vergelijkbaar, ook al verschilt de syntaxis:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({
  name: "My Server",
  version: "1.0.0",
});

De keuze hangt minder af van de mogelijkheden en meer van het ecosysteem waarin uw server zijn data ophaalt. Een server die via SQLAlchemy een database bevraagt of bestaande verwerkingsscripts hergebruikt, zal natuurlijk in Python zijn; een server die steunt op een bestaande Express-applicatie blijft in TypeScript. De onderstaande tabel vat de praktische verschillen samen.

CriteriumMCPServer (Python SDK)MCP SDK (TypeScript)
RijpheidZeer volwassenVolwassen
Decorators@app.tool()server.tool()-methode
HTTP-transportIngebouwd (FastAPI)Ingebouwd (Express)
CommunityGrootGroot

Een projectstructuur die standhoudt

De aanbevolen mapstructuur scheidt vier verantwoordelijkheden: wat het model ziet (tools/), wat toegang heeft tot data (services/), wat de toegang regelt (auth/), en wat de omgeving beschrijft (config.py, .env).

my-mcp-server/
├── server.py              # FastAPI entry point + MCP mounting
├── tools/
│   ├── __init__.py
│   ├── project_tools.py   # Project management tools
│   ├── file_tools.py      # File management tools
│   └── search_tools.py    # Search tools
├── services/
│   ├── __init__.py
│   ├── database.py        # Database access
│   └── external_api.py    # External API calls
├── auth/
│   ├── __init__.py
│   └── middleware.py       # Authentication middleware
├── config.py              # Configuration (env vars)
├── Dockerfile             # Containerization
├── requirements.txt       # Python dependencies
├── .env                   # Environment variables (not committed)
└── tests/
    ├── test_tools.py
    └── test_integration.py

Deze scheiding heeft een direct, concreet gevolg: uw tools bevatten geen SQL- of HTTP-aanroepen meer, alleen validatie en delegatie aan een service. U kunt dan bedrijfslogica testen zonder via MCP te gaan, en van database wisselen zonder ook maar één docstring aan te raken die het model ziet.

Het entry point: server.py

Het hoofdbestand doet niets anders dan componenten assembleren: het maakt de FastAPI-applicatie aan, stapelt middlewares op en mount elke MCP-server op zijn eigen route.

# 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

# Each MCP server must start its session manager
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
        yield

# FastAPI application
api = FastAPI(
    title="My MCP Server",
    version="1.0.0",
    lifespan=lifespan,
)

# CORS for web clients
api.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

# Authentication middleware
api.add_middleware(AuthMiddleware)

# Public hostname under which servers are served (otherwise: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])

# Mount MCP servers on distinct routes
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))

# Home page (optional but useful)
@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)

Mounten op verschillende routes stelt gebruikers in staat alleen het domein in te schakelen dat ze nodig hebben: iemand die documentatie zoekt, verbindt met /search/mcp zonder dat hem projectmanagementtools worden aangeboden. Wat de homepagina betreft, deze lijkt triviaal totdat een collega vraagt naar de exacte endpoint-URL; deze antwoordt voor u en dient als health check.

Eén tools-module per domein

Elk bestand in de map tools/ declareert zijn eigen MCPServer-object en groepeert tools uit hetzelfde functionele domein. Zo ziet de projectmanagementmodule eruit, die eerder door server.py is geïmporteerd:

# 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()

Merk op hoe beknopt de functierompjes zijn: slechts twee regels elk, omdat data-toegang leeft in services/database.py. De tool beschrijft eenvoudigweg zijn contract met het model en delegeert.

Gecentraliseerde configuratie

Elke waarde die verschilt tussen uw machine en de productieserver moet uit de omgeving komen, nooit uit code. Een enkel bestand config.py verzamelt deze variabelen met hun standaardwaarden:

# 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()

De parameter max_results illustreert het voordeel van deze aanpak: op de dag dat een tool te veel resultaten retourneert en de context van het model verzadigt, past u een omgevingsvariabele aan en start u opnieuw op, zonder code opnieuw te implementeren.

Fouten die het model kan lezen

Een Python-exception die abrupt naar boven borrelt, vertelt het model niets: het ziet een mislukking zonder te begrijpen waarom, en probeert het vaak identiek opnieuw. Standaardiseer in plaats daarvan een expliciet foutresponsformaat met een code en een bericht.

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")

Het verschil is doorslaggevend in het gesprek. Geconfronteerd met not_found begrijpt het model dat het eerst projecten moet opsommen om de juiste ID te vinden; geconfronteerd met een stille exception geeft het op of raakt het in een loop.

Stateful of stateless

Een stateful server behoudt informatie tussen aanroepen: een database in het geheugen, gebruikerssessies, werkcontext. Dit komt vaak voor bij beheerservers, zoals de taakmanager uit de vorige les. Een stateless server behandelt elk verzoek onafhankelijk en onthoudt niets—aanbevolen voor pure berekening of transformatie, en maakt horizontale schaling mogelijk omdat elke instantie elk verzoek kan afhandelen. SDK v2 maakt dit mogelijk met een HTTP-applicatieparameter (die niet langer aan de constructor wordt doorgegeven). Merk op dat met de specificatie van 28-07-2026 het protocol zelf geen sessies meer kent: deze instelling betreft alleen clients die een eerdere protocolversie onderhandelen.

app = MCPServer("Stateless Server")

# Setting is passed when building the HTTP application
mcp_app = app.streamable_http_app(stateless_http=True)

Beslis deze vraag voordat u uw tools schrijft, niet erna: de overstap van een stateful naar een stateless server betekent dat alle state naar een externe database moet worden verplaatst, wat een groot deel van de code herschrijft.

Belangrijkste punten

  • Splits uw tools op in thematische modules in een map tools/
  • Gebruik FastAPI als HTTP-basis, mount MCP-servers op toegewijde routes en geef hun lifespan door
  • Centraliseer configuratie via omgevingsvariabelen
  • Standaardiseer formaten voor foutresponsen zodat het model ze kan gebruiken
  • Kies tussen stateful (databeheer) en stateless (pure berekening)
  • Voeg een /-homepagina toe om uw MCP-endpoints te documenteren