Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Arhitektura prilagođenog MCP poslužitelja

Lekcija 10 od 14 Ažurirano 2. studenoga 2026. Programer
Na ovoj stranici
  1. Projektiranje produkcijskog MCP poslužitelja
  2. Odabir okvira
  3. Struktura projekta koja traje
  4. Ulazna točka: server.py
  5. Jedan modul alata po domeni
  6. Centralizirana konfiguracija
  7. Greške koje model može pročitati
  8. Sa stanjem ili bez stanja
  9. Ključne točke

Ažurirano 2. studenoga 2026. — MCP Python SDK v2. Ovaj tečaj sada prati verziju 2 SDK-a mcp (2.3.0 od 2. listopada 2026.): MCPServer zamjenjuje FastMCP, postavke transporta prelaze u run() ili streamable_http_app(), a aplikacija izložena pod stvarnim nazivom hosta mora deklarirati taj naziv hosta (transport_security). Ovo je također verzija koju zahtijeva Mistral SDK: dodatak mistralai[agents] zahtijeva mcp>=2.2.0,<3.0. Izvori: Što je novo u v2 · Vodič za migraciju · Implementacija i skaliranje.

Projektiranje produkcijskog MCP poslužitelja

MCP prototip stane u datoteku od četrdesetak redaka, što je često dovoljno da se uvjeri tim. Prelazak na stvarnu upotrebu mijenja sve: poslužitelj poziva više ljudi, alati se množe, konfiguracija varira ovisno o okruženju, a jedna datoteka postaje nemoguća za održavanje. Ova lekcija pokriva arhitektonske odluke koje sprječavaju udaranje u taj zid – odabir okvira, strukturiranje projekta, upravljanje konfiguracijom i greškama te odluka između poslužitelja sa stanjem (stateful) i bez stanja (stateless).

Odabir okvira

U Pythonu, klasa MCPServer iz službenog SDK-a (ranije FastMCP) standardni je alat. Ona izlaže API temeljen na dekoratorima i rukuje MCP protokolom umjesto tebe, tako da poslužitelj oživi u tri retka:

from mcp.server.mcpserver import MCPServer

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

Timovi koji rade s JavaScriptom i TypeScriptom imaju službeni MCP SDK koji objavljuje Anthropic. Logika je usporediva čak i ako se sintaksa razlikuje:

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

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

Odabir manje ovisi o mogućnostima, a više o ekosustavu iz kojeg će tvoj poslužitelj dohvaćati podatke. Poslužitelj koji upituje bazu podataka putem SQLAlchemy ili ponovno koristi postojeće skripte za obradu prirodno će biti u Pythonu; poslužitelj oslonjen na postojeću Express aplikaciju ostat će u TypeScriptu. Donja tablica sažima praktične razlike.

KriterijMCPServer (Python SDK)MCP SDK (TypeScript)
ZrelostVrlo zrelaZrela
Dekoratori@app.tool()Metoda server.tool()
HTTP TransportUgrađen (FastAPI)Ugrađen (Express)
ZajednicaVelikaVelika

Struktura projekta koja traje

Preporučena struktura direktorija razdvaja četiri odgovornosti: što model vidi (tools/), što pristupa podacima (services/), što kontrolira pristup (auth/) i što opisuje okruženje (config.py, .env).

my-mcp-server/
├── server.py              # Ulazna točka FastAPI + montaža MCP-a
├── tools/
│   ├── __init__.py
│   ├── project_tools.py   # Alati za upravljanje projektima
│   ├── file_tools.py      # Alati za upravljanje datotekama
│   └── search_tools.py    # Alati za pretraživanje
├── services/
│   ├── __init__.py
│   ├── database.py        # Pristup bazi podataka
│   └── external_api.py    # Pozivi vanjskom API-ju
├── auth/
│   ├── __init__.py
│   └── middleware.py       # Middleware za autentifikaciju
├── config.py              # Konfiguracija (varijable okruženja)
├── Dockerfile             # Kontejnerizacija
├── requirements.txt       # Python ovisnosti
├── .env                   # Varijable okruženja (ne commitaju se)
└── tests/
    ├── test_tools.py
    └── test_integration.py

Ovo razdvajanje ima izravnu, konkretnu posljedicu: tvoji alati više ne sadrže SQL ili HTTP pozive, već samo validaciju i delegiranje servisu. Tada možeš testirati poslovnu logiku bez prolaska kroz MCP i mijenjati baze podataka bez diranja ijednog docstringa koji model vidi.

Ulazna točka: server.py

Glavna datoteka ne radi ništa drugo osim što sastavlja komponente: stvara FastAPI aplikaciju, slaže middlewareove i montira svaki MCP poslužitelj na vlastitu rutu.

# 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

# Svaki MCP poslužitelj mora pokrenuti svoj upravitelj sesijom
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
        yield

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

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

# Middleware za autentifikaciju
api.add_middleware(AuthMiddleware)

# Javni naziv hosta pod kojim se poslužuju poslužitelji (inače: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])

# Montaža MCP poslužitelja na različite rute
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))

# Početna stranica (opcionalno, ali korisno)
@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)

Montaža na različite rute omogućuje korisnicima da omoguće samo domenu koja im treba: netko tko traži dokumentaciju spaja se na /search/mcp bez da mu se nude alati za upravljanje projektima. Što se tiče početne stranice, čini se trivijalnom dok kolega ne pita za točan URL krajnje točke; ona odgovara umjesto tebe i služi kao zdravstvena provjera.

Jedan modul alata po domeni

Svaka datoteka u mapi tools/ deklarira vlastiti objekt MCPServer i grupira alate iz iste funkcionalne domene. Evo kako izgleda modul za upravljanje projektima, koji je server.py ranije uvezao:

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

Primijeti kako su tijela funkcija kratka: samo dva retka svako, jer pristup podacima živi u services/database.py. Alat jednostavno opisuje svoj ugovor modelu i delegira posao.

Centralizirana konfiguracija

Svaka vrijednost koja se mijenja između tvog računala i produkcijskog poslužitelja mora dolaziti iz okruženja, nikada iz koda. Jedna datoteka config.py prikuplja ove varijable s njihovim zadanim vrijednostima:

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

Parametar max_results ilustrira prednost ovog pristupa: dan kada alat vrati previše rezultata i zasiti kontekst modela, prilagodiš varijablu okruženja i ponovno pokreneš, bez ponovne implementacije koda.

Greške koje model može pročitati

Python iznimka koja naglo iskoči modelu ne govori ništa: on vidi neuspjeh, ali ne razumije zašto, pa često pokušava isto iznova. Umjesto toga, standardiziraj eksplicitan format odgovora za grešku s kodom i porukom.

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

Razlika je odlučujuća u razgovoru. Suočen s not_found, model shvaća da prvo mora izlistati projekte kako bi pronašao ispravan ID; suočen s tiho iznimkom, odustaje ili ulazi u petlju.

Sa stanjem ili bez stanja

Poslužitelj sa stanjem (stateful) zadržava informacije između poziva: baza podataka u memoriji, korisničke sesije, kontekst rada. To je uobičajeno za poslužitelje za upravljanje, poput upravitelja zadacima iz prethodne lekcije. Poslužitelj bez stanja (stateless) obrađuje svaki zahtjev neovisno, ne pamteći ništa – preporučuje se za čisto računanje ili transformaciju i omogućuje horizontalno skaliranje jer bilo koja instanca može obraditi bilo koji zahtjev. SDK v2 to omogućuje putem parametra HTTP aplikacije (više se ne prosljeđuje konstruktoru). Imaj na umu da sa specifikacijom od 28. srpnja 2026. sam protokol više ne poznaje sesije: ova postavka odnosi se samo na klijente koji pregovaraju o starijoj verziji protokola.

app = MCPServer("Stateless Server")

# Postavka se prosljeđuje prilikom izgradnje HTTP aplikacije
mcp_app = app.streamable_http_app(stateless_http=True)

Ovo pitanje odluči prije nego što napišeš svoje alate, a ne poslije: prelazak s poslužitelja sa stanjem na onaj bez stanja znači premještanje cijelog stanja u vanjsku bazu podataka, što prepisuje dobar dio koda.

Ključne točke

  • Razdvoj svoje alate u tematske module u mapi tools/
  • Koristi FastAPI kao HTTP bazu, montiraj MCP poslužitelje na namjenske rute i proslijedi njihov životni vijek (lifespan)
  • Centraliziraj konfiguraciju putem varijabli okruženja
  • Standardiziraj formate odgovora za greške kako bi ih model mogao iskoristiti
  • Odaberi između sa stanjem (upravljanje podacima) i bez stanja (čisto računanje)
  • Dodaj početnu stranicu / za dokumentiranje svojih MCP krajnjih točaka