Arkitektur för en anpassad MCP-server
På denna sida
Uppdaterad 2 november 2026 — MCP Python SDK v2. Denna kurs följer nu version 2 av
mcp-SDK:t (2.3.0 per den 2 oktober 2026):MCPServerersätterFastMCP, transportinställningar flyttas tillrun()ellerstreamable_http_app(), och en applikation som exponeras under ett riktigt värdnamn måste deklarera detta värdnamn (transport_security). Detta är också den version som krävs av Mistral SDK: tilläggetmistralai[agents]krävermcp>=2.2.0,<3.0. Källor: Vad är nytt i v2 · Migreringsguide · Distribuera och skala.
Att designa en MCP-server för produktion
En MCP-prototyp får plats i en fil på fyrtio rader, och det räcker ofta för att övertyga ett team. Men när du går över till verklig användning förändras allt: flera personer anropar servern, antalet verktyg växer, konfigurationen varierar mellan miljöer och den enda filen blir omöjlig att underhålla. I denna lektion går vi igenom de arkitektoniska beslut som hindrar dig från att köra in i väggen – val av ramverk, strukturering av ditt projekt, hantering av konfiguration och fel, samt valet mellan tillståndsbärande och tillståndslösa servrar.
Välja ditt ramverk
I Python är klassen MCPServer från det officiella SDK:t (tidigare FastMCP) standardverktyget. Den erbjuder ett API baserat på dekoratorer och hanterar MCP-protokollet åt dig, så att en server vaknar till liv på tre rader:
from mcp.server.mcpserver import MCPServer
app = MCPServer(
"My Server",
instructions="MCP Server for project management",
)
Team som arbetar med JavaScript och TypeScript har tillgång till det officiella MCP SDK:t publicerat av Anthropic. Logiken är jämförbar även om syntaxen skiljer sig:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({
name: "My Server",
version: "1.0.0",
});
Valet beror mindre på kapacitet och mer på det ekosystem där din server ska hämta sina data. En server som frågar en databas via SQLAlchemy eller återanvänder befintliga bearbetningsskript kommer naturligt att skrivas i Python; en server som bygger på en befintlig Express-applikation stannar i TypeScript. Tabellen nedan sammanfattar de praktiska skillnaderna.
| Kriterium | MCPServer (Python SDK) | MCP SDK (TypeScript) |
|---|---|---|
| Mognad | Mycket mogen | Mogen |
| Dekoratorer | @app.tool() | Metod server.tool() |
| HTTP-transport | Inbyggd (FastAPI) | Inbyggd (Express) |
| Community | Stort | Stort |
En projektstruktur som håller över tid
Den rekommenderade katalogstrukturen separerar fyra ansvarsområden: vad modellen ser (tools/), vad som kommer åt data (services/), vad som styr åtkomst (auth/) och vad som beskriver miljön (config.py, .env).
my-mcp-server/
├── server.py # FastAPI-ingångspunkt + MCP-montering
├── tools/
│ ├── __init__.py
│ ├── project_tools.py # Verktyg för projekthantering
│ ├── file_tools.py # Verktyg för filhantering
│ └── search_tools.py # Sökverktyg
├── services/
│ ├── __init__.py
│ ├── database.py # Databasåtkomst
│ └── external_api.py # Anrop till externa API:er
├── auth/
│ ├── __init__.py
│ └── middleware.py # Autentiseringsmiddleware
├── config.py # Konfiguration (miljövariabler)
├── Dockerfile # Containerisering
├── requirements.txt # Python-beroenden
├── .env # Miljövariabler (checkas inte in)
└── tests/
├── test_tools.py
└── test_integration.py
Denna separation får en direkt och konkret konsekvens: dina verktyg innehåller inte längre SQL eller HTTP-anrop, endast validering och delegering till en tjänst. Du kan då testa affärslogiken utan att gå via MCP, och byta databas utan att röra en enda docstring som modellen ser.
Ingångspunkten: server.py
Huvudfilen gör ingenting annat än att sätta ihop komponenter: den skapar FastAPI-applikationen, lägger till middleware och monterar varje MCP-server på sin egen rutt.
# 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
# Varje MCP-server måste starta sin sessionshanterare
@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 för webbklienter
api.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)
# Autentiseringsmiddleware
api.add_middleware(AuthMiddleware)
# Offentligt värdnamn under vilket servrarna levereras (annars: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])
# Montera MCP-servrar på distinkta rutter
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))
# Hemside (valfri men användbar)
@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)
Att montera på distinkta rutter låter användare aktivera endast den domän de behöver: någon som söker efter dokumentation ansluter till /search/mcp utan att få erbjudanden om projekthanteringsverktyg. Vad gäller hemsidan kan den verka trivial tills en kollega frågar efter den exakta slutpunkts-URL:en; den svarar åt dig och fungerar som en hälsokontroll.
Ett verktygsmodul per domän
Varje fil i mappen tools/ deklarerar sitt eget MCPServer-objekt och grupperar verktyg från samma funktionella domän. Så här ser modulen för projekthantering ut, som importerades tidigare av 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ägg märke till hur korta funktionskropparna är: bara två rader var, eftersom dataåtkomsten finns i services/database.py. Verktyget beskriver helt enkelt sitt kontrakt för modellen och delegerar arbetet.
Centraliserad konfiguration
Alla värden som skiljer sig mellan din maskin och produktionsservern måste komma från miljön, aldrig från koden. En enda fil, config.py, samlar dessa variabler med sina standardvärden:
# 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()
Parametern max_results illustrerar fördelen med detta tillvägagångssätt: den dag ett verktyg returnerar för många resultat och mättar modellens kontext, justerar du en miljövariabel och startar om, utan att behöva distribuera om kod.
Fel som modellen kan läsa
Ett Python-undantag som bubblar upp abrupt säger modellen ingenting: den ser ett misslyckande utan att förstå varför, och försöker ofta igen på samma sätt. Standardisera istället ett explicit felresponsformat med en kod och ett meddelande.
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")
Skillnaden är avgörande i konversationen. Konfronterad med not_found förstår modellen att den först måste lista projekt för att hitta rätt ID; konfronterad med ett tyst undantag ger den upp eller hamnar i en loop.
Tillståndsbärande eller tillståndslös
En tillståndsbärande (stateful) server behåller information mellan anrop: databas i minnet, användarsessioner, arbetskontext. Detta är vanligt för hanteringsservrar, som uppgiftshanteraren från föregående lektion. En tillståndslös (stateless) server hanterar varje begäran oberoende och kommer inte ihåg något – rekommenderat för ren beräkning eller transformation, och möjliggör horisontell skalning eftersom vilken instans som helst kan hantera vilken begäran som helst. SDK v2 möjliggör detta med en parameter för HTTP-applikationen (som inte längre skickas till konstruktorn). Observera att med specifikationen från 2026-07-28 känner protokollet i sig inte längre till sessioner: denna inställning gäller endast klienter som förhandlar om en tidigare protokollversion.
app = MCPServer("Stateless Server")
# Inställningen skickas när HTTP-applikationen byggs
mcp_app = app.streamable_http_app(stateless_http=True)
Beslut detta innan du skriver dina verktyg, inte efter: att gå från en tillståndsbärande till en tillståndslös server innebär att flytta allt tillstånd till en extern databas, vilket skriver om en god del av koden.
Viktiga punkter
- Separera dina verktyg i tematiska moduler i en mapp
tools/ - Använd FastAPI som HTTP-bas, montera MCP-servrar på dedikerade rutter och skicka deras lifespan
- Centralisera konfiguration via miljövariabler
- Standardisera format för felrespons så att modellen kan använda dem
- Välj mellan tillståndsbärande (datahantering) och tillståndslös (ren beräkning)
- Lägg till en hemsida
/för att dokumentera dina MCP-slutpunkter