Mukautetun MCP-palvelimen arkkitehtuuri
Tällä sivulla
Päivitetty 2. marraskuuta 2026 — MCP Python SDK v2. Tämä kurssi noudattaa nyt
mcp-kehityspaketin versiota 2 (2.3.0 tilanteen mukaan 2. lokakuuta 2026):MCPServerkorvaaFastMCP:n, kuljetusasetukset siirtyvät metodeihinrun()taistreamable_http_app(), ja todellisen isäntänimen alla julkaistun sovelluksen on ilmoitettava kyseinen isäntänimi (transport_security). Tämä on myös Mistral SDK:n vaatima versio:mistralai[agents]-lisäosa vaatiimcp>=2.2.0,<3.0. Lähteet: Mitä uutta versiossa v2 · Migraatio-opas · Käyttöönotto ja skaalaus.
Tuotantokäyttöön tarkoitetun MCP-palvelimen suunnittelu
MCP-prototyyppi mahtuu neljänkymmenen rivin tiedostoon, ja se riittää usein vakuuttamaan tiimin. Siirtyminen todelliseen käyttöön muuttaa kuitenkin kaiken: palvelinta kutsuu useita henkilöitä, työkaluja tulee lisää, konfiguraatio vaihtelee ympäristöjen välillä, ja yhdestä tiedostosta tulee mahdoton ylläpitää. Tämä oppitunti käsittelee arkkitehtuuriratkaisuja, jotka estävät tämän seinään törmäämisen: kehyksen valinta, projektin rakenteen suunnittelu, konfiguraation ja virheiden hallinta sekä päätös tilallisen ja tilattoman palvelimen välillä.
Kehyksen valinta
Pythonissa virallisen SDK:n MCPServer-luokka (aiemmin FastMCP) on standardityökalu. Se tarjoaa dekorattoreihin perustuvan rajapinnan ja hoitaa MCP-protokollan puolestasi, joten palvelin herää henkiin kolmella rivillä:
from mcp.server.mcpserver import MCPServer
app = MCPServer(
"My Server",
instructions="MCP Server for project management",
)
JavaScript- ja TypeScript-tiimeillä on Anthropicin julkaisema virallinen MCP SDK. Logiikka on vertailukelpoinen, vaikka syntaksi eroaakin:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({
name: "My Server",
version: "1.0.0",
});
Valinta riippuu vähemmän ominaisuuksista ja enemmän siitä ekosysteemistä, josta palvelimesi hakee tietonsa. Palvelin, joka kyselyttää tietokantaa SQLAlchemyn kautta tai käyttää uudelleen olemassa olevia käsittelyskriptejä, on luontevasti Pythonilla tehty; palvelin, joka nojaa olemassa olevaan Express-sovellukseen, pysyy TypeScriptissä. Alla oleva taulukko tiivistää käytännön erot.
| Kriteri | MCPServer (Python SDK) | MCP SDK (TypeScript) |
|---|---|---|
| Kypsyys | Erittäin kypsä | Kypsä |
| Dekorattorit | @app.tool() | server.tool()-metodi |
| HTTP-kuljetus | Sisäänrakennettu (FastAPI) | Sisäänrakennettu (Express) |
| Yhteisö | Suuri | Suuri |
Projektille kestävä rakenne
Suositeltu hakemistorakenne erottaa neljä vastuualuetta: mitä malli näkee (tools/), mitä käyttää dataa (services/), mitä hallitsee pääsyä (auth/) ja mitä kuvaa ympäristöä (config.py, .env).
my-mcp-server/
├── server.py # FastAPI:n sisäänmenopiste + MCP:n kiinnitys
├── tools/
│ ├── __init__.py
│ ├── project_tools.py # Projektinhallintatyökalut
│ ├── file_tools.py # Tiedostonhallintatyökalut
│ └── search_tools.py # Hakutyökalut
├── services/
│ ├── __init__.py
│ ├── database.py # Tietokantayhteys
│ └── external_api.py # Ulkoiset API-kutsut
├── auth/
│ ├── __init__.py
│ └── middleware.py # Todennusmiddleware
├── config.py # Konfiguraatio (ympäristömuuttujat)
├── Dockerfile # Kontitus
├── requirements.txt # Python-riippuvuudet
├── .env # Ympäristömuuttujat (ei commitoida)
└── tests/
├── test_tools.py
└── test_integration.py
Tällä erottelulla on suora ja konkreettinen seuraus: työkalusi eivät enää sisällä SQL- tai HTTP-kutsuja, vaan ainoastaan validoinnin ja delegoinnin palvelulle. Voit sitten testata liiketoimintalogiikkaa kulkematta MCP:n kautta ja vaihtaa tietokantaa koskematta yhteenkään mallin näkemään docstringiin.
Sisäänmenopiste: server.py
Päätiedosto tekee vain komponenttien kokoamisen: se luo FastAPI-sovelluksen, pinoo middlewaret ja kiinnittää jokaisen MCP-palvelimen omalle reitilleen.
# server.py
"""MCP-palvelimen sisäänmenopiste."""
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
# Jokaisen MCP-palvelimen on käynnistettävä istunnonhallintansa
@asynccontextmanager
async def lifespan(app: FastAPI):
async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
yield
# FastAPI-sovellus
api = FastAPI(
title="My MCP Server",
version="1.0.0",
lifespan=lifespan,
)
# CORS verkkoselaimille
api.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)
# Todennusmiddleware
api.add_middleware(AuthMiddleware)
# Julkinen isäntänimi, jonka alla palvelimia tarjotaan (muuten: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])
# Kiinnitä MCP-palvelimet erillisille reiteille
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))
# Etusivu (valinnainen mutta hyödyllinen)
@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)
Kiinnitys erillisille reiteille antaa käyttäjille mahdollisuuden ottaa käyttöön vain tarvittavan toimialueen: dokumentaatiota etsivä henkilö yhdistää osoitteeseen /search/mcp saamatta tarjolle projektinhallintatyökaluja. Mitä tulee etusivuun, se vaikuttaa triviaalilta, kunnes kollega kysyy tarkan päätepiste-URL:n; se vastaa puolestasi ja toimii terveystarkistuksena.
Yksi työkalumoduuli toimialuetta kohden
Jokainen tools/-kansion tiedosto julistaa oman MCPServer-objektinsa ja ryhmittelee saman toiminnallisen alueen työkalut. Tältä projektinhallintamoduuli näyttää; server.py toi sen aiemmin sisään:
# tools/project_tools.py
"""MCP-työkalut projektinhallintaan."""
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:
"""Luo uuden projektin.
Args:
name: Projektin nimi (2–100 merkkiä)
description: Projektin kuvaus (valinnainen)
Returns:
JSON luodun projektin tiedoilla
"""
project = await db.projects.create(name=name, description=description)
return project.to_json()
@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
"""Listaa projektit tilan mukaan.
Args:
status: Suodata tilan mukaan: active, archived, all (oletus: active)
Returns:
JSON projektien listalla
"""
projects = await db.projects.list(status=status)
return projects.to_json()
Huomaa, kuinka lyhyitä funktion rungot ovat: vain kaksi riviä kummassakin, koska datan käyttö asuu tiedostossa services/database.py. Työkalu vain kuvaa sopimuksensa mallille ja delegoi tehtävän eteenpäin.
Keskitetty konfiguraatio
Kaikkien arvojen, jotka muuttuvat koneesi ja tuotantopalvelimen välillä, on tultava ympäristöstä, ei koodista. Yksi config.py-tiedosto kerää nämä muuttujat oletusarvoineen:
# config.py
"""MCP-palvelimen konfiguraatio."""
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()
Parametri max_results havainnollistaa tämän lähestymistavan hyödyn: sinä päivänä, kun työkalu palauttaa liian monta tulosta ja kyllästää mallin kontekstin, säädät ympäristömuuttujaa ja käynnistät uudelleen ilman koodin uudelleenkäyttöönottoa.
Mallin luettavat virheet
Python-poikkeus, joka nousee äkillisesti pinnalle, ei kerro mallille mitään: se näkee epäonnistumisen ymmärtämättä syytä ja usein yrittää samaa uudelleen. Sen sijaan standardoi eksplisiittinen virhevastausformaatti, jossa on koodi ja viesti.
import json
def error_response(message: str, code: str = "error") -> str:
"""Muotoilee standardoidun virheilmoituksen."""
return json.dumps({
"success": False,
"error": {"code": code, "message": message}
}, ensure_ascii=False)
@project_mcp.tool()
async def get_project(project_id: str) -> str:
"""Hakee projektin tiedot ID:n perusteella."""
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")
Ero on ratkaiseva keskustelussa. Kohdatessaan not_found-virheen malli ymmärtää, että sen on ensin listattava projektit löytääkseen oikean ID:n; kohdatessaan hiljaisen poikkeuksen se luovuttaa tai jää silmukkaan.
Tilallinen vai tilaton
Tilallinen palvelin säilyttää tietoa kutsujen välillä: muistissa oleva tietokanta, käyttäjäistunnot, työkonteksti. Tämä on yleistä hallintapalvelimilla, kuten edellisen oppitunnin tehtävienhallinnassa. Tilaton palvelin käsittelee jokaisen pyynnön itsenäisesti muistamatta mitään – suositeltavaa puhtaaseen laskentaan tai muunnokseen, ja mahdollistaa vaakasuoran skaalautuvuuden, sillä mikä tahansa instanssi voi hoitaa minkä tahansa pyynnön. SDK v2 mahdollistaa tämän HTTP-sovellusparametrilla (sitä ei enää välitetä konstruktorille). Huomaa, että 28.7.2026 spesifikaation mukaan protokolla ei enää tunne istuntoja: tämä asetus koskee vain asiakkaita, jotka neuvottelevat aikaisempaa protokollaversiota.
app = MCPServer("Stateless Server")
# Asetus välitetään HTTP-sovellusta rakennettaessa
mcp_app = app.streamable_http_app(stateless_http=True)
Päätä tämä kysymys ennen työkalujen kirjoittamista, älä niiden jälkeen: siirtyminen tilallisesta tilattomaan palvelimeen tarkoittaa kaiken tilan siirtämistä ulkoiseen tietokantaan, mikä kirjoittaa uudelleen hyvän osan koodista.
Keskeiset asiat
- Erota työkalusi teemakohtaisiin moduuleihin
tools/-kansiossa - Käytä FastAPI:ta HTTP-pohjana, kiinnitä MCP-palvelimet omille reiteilleen ja välitä niiden lifespan
- Keskitä konfiguraatio ympäristömuuttujien kautta
- Standardoi virhevastauksien formaatit, jotta malli voi hyödyntää niitä
- Valitse tilallisen (datanhallinta) ja tilattoman (puhdas laskenta) välillä
- Lisää
/-etusivu dokumentoidaksesi MCP-päätepisteesi