Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Mukautetun MCP-palvelimen arkkitehtuuri

Oppitunti 10 / 14 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Tuotantokäyttöön tarkoitetun MCP-palvelimen suunnittelu
  2. Kehyksen valinta
  3. Projektille kestävä rakenne
  4. Sisäänmenopiste: server.py
  5. Yksi työkalumoduuli toimialuetta kohden
  6. Keskitetty konfiguraatio
  7. Mallin luettavat virheet
  8. Tilallinen vai tilaton
  9. Keskeiset asiat

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): MCPServer korvaa FastMCP:n, kuljetusasetukset siirtyvät metodeihin run() tai streamable_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 vaatii mcp>=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.

KriteriMCPServer (Python SDK)MCP SDK (TypeScript)
KypsyysErittäin kypsäKypsä
Dekorattorit@app.tool()server.tool()-metodi
HTTP-kuljetusSisäänrakennettu (FastAPI)Sisäänrakennettu (Express)
YhteisöSuuriSuuri

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