Przejdź do głównej treści
Polski— Wybierz język
Menu

Wdrożenie serwera MCP do środowiska produkcyjnego

Lekcja 12 z 14 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Od prototypu do serwera produkcyjnego
  2. Opcja 1: Hugging Face Spaces
  3. Opcja 2: Docker
  4. Opcje 3 i 4: Wdrożenia zarządzane
  5. Zabezpieczanie wdrożenia
  6. Obserwacja tego, co się dzieje
  7. Kluczowe wnioski

Aktualizacja z 2 listopada 2026 r. — Le Chat to teraz Vibe. Od 28 maja 2026 r. Le Chat zmienił nazwę na Vibe (nadal dostępny pod adresem chat.mistral.ai): to pojedynczy agent do pracy i kodowania, który zachowuje Twoje konwersacje, ustawienia i subskrypcje. Legacyjne doświadczenie Le Chat pozostaje dostępne w trybie Chat; w trybie Work agenci to teraz umiejętności (wywoływane za pomocą @), pamięci tworzą bazę wiedzy, a głębokie badania to umiejętność Deep Research. Plany noszą teraz nazwy Mistral Free, Pro, Team i Enterprise. W tej lekcji używamy nazwy Vibe; niektóre opisane tu menu mogły zmienić nazwy lub lokalizację.

Aktualizacja z 2 listopada 2026 r. — MCP Python SDK w wersji 2. Kurs opiera się teraz na wersji 2 SDK mcp (2.3.0 według stanu na 2 października 2026 r.): MCPServer zastępuje FastMCP, ustawienia transportu przeniesiono do run() lub streamable_http_app(), a aplikacja wystawiona pod rzeczywistą nazwą hosta musi tę nazwę zadeklarować (transport_security). Jest to również wersja wymagana przez Mistral SDK: dodatek mistralai[agents] wymaga mcp>=2.2.0,<3.0. Źródła: Co nowego w v2 · Przewodnik migracyjny · Wdrażanie i skalowanie.

Od prototypu do serwera produkcyjnego

Twój serwer działa lokalnie, a ngrok udostępnia go światu tylko na potrzeby demonstracji. Problem zaczyna się, gdy ktoś inny musi z niego skorzystać: zamykasz terminal, URL przestaje działać, a każde połączenie skonfigurowane przez Twoich kolegów ulega awarii. Przejście do produkcji oznacza w istocie uzyskanie stabilnego adresu, dostępnego 24/7, obsługiwanego przez HTTPS. Cztery opcje doprowadzą Cię do tego celu, od najszybszej do najbardziej kontrolowanej. Twój wybór zależy głównie od wrażliwości Twoich danych oraz od tego, jak dużą kontrolę chcesz mieć nad infrastrukturą.

Opcja 1: Hugging Face Spaces

Hugging Face Spaces udostępnia darmowe maszyny wirtualne bez GPU, co w zupełności wystarcza dla serwera MCP przesyłającego wywołania API. To najszybsza droga do rzeczywistego wdrożenia: trzy pliki i git push.

mon-mcp-space/
├── app.py              # FastAPI + serwer MCP
├── requirements.txt    # Zależności
└── README.md           # Metadane Space

Plik app.py zachowuje dokładnie taką samą strukturę, jaką widziałeś do tej pory, z tym wyjątkiem, że wartości poufne są odczytywane ze zmiennych środowiskowych — HF Secrets wstrzykują je w tym miejscu:

# app.py
"""Serwer MCP wdrożony na Hugging Face Spaces."""

import os
from contextlib import asynccontextmanager

from fastapi import FastAPI
from mcp.server.mcpserver import MCPServer
from mcp.server.transport_security import TransportSecuritySettings

mcp = MCPServer("My Production Server")

@mcp.tool()
def hello(name: str) -> str:
    """Powitanie osoby.

    Args:
        name: Imię osoby

    Returns:
        Wiadomość powitalna
    """
    return f"Hello {name} from Hugging Face Spaces!"

@asynccontextmanager
async def lifespan(app: FastAPI):
    async with mcp.session_manager.run():
        yield

# Nazwa hosta Space, w formie <user>-<space>.hf.space
SPACE_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[SPACE_HOST, f"{SPACE_HOST}:*"])

api = FastAPI(lifespan=lifespan)
api.mount("/mcp-endpoint", mcp.streamable_http_app(transport_security=security))

# Dla zmiennych wrażliwych użyj HF Secrets
API_KEY = os.environ.get("MY_API_KEY", "")

Osobliwością platformy jest plik README, którego nagłówek YAML steruje budową Space. Pole app_port musi odpowiadać portowi, na którym serwer faktycznie nasłuchuje; w przeciwnym razie wdrožení powiedzie się, ale usługa pozostanie niedostępna:

---
title: My MCP Server
emoji: 🔧
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
---
# Utwórz Space na huggingface.co
# Wypchnij kod
git push
# Space wdraża się automatycznie

Twój punkt końcowy przyjmuje wtedy postać https://your-username-mon-mcp-space.hf.space/mcp-endpoint/mcp, obsługiwany przez HTTPS. Pozostaje jeszcze jeden krok konfiguracji: zadeklaruj tę nazwę hosta, your-username-mon-mcp-space.hf.space, w zmiennej MCP_PUBLIC_HOST w ustawieniach Space. Bez tego SDK odrzuci każde żądanie błędem 421 Invalid Host header.

Opcja 2: Docker

Gdy tylko serwer zacznie dotykać danych wewnętrznych, hosting na własnej infrastrukturze staje się regułą, a Docker jest standardowym formatem. Plik Dockerfile wymaga zaledwie kilku instrukcji, przy czym instalacja zależności powinna poprzedzać kopiowanie kodu, aby wykorzystać buforowanie warstw podczas przebudowy:

FROM python:3.12-slim

WORKDIR /app

# Instalacja zależności
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Kopiowanie kodu
COPY . .

# Udostępnienie portu
EXPOSE 8000

# Uruchomienie serwera
CMD ["uvicorn", "server:api", "--host", "0.0.0.0", "--port", "8000"]
fastapi>=0.115.0
uvicorn>=0.30.0
mcp>=2.2,<3
httpx>=0.27.0   # tylko jeśli Twoje narzędzia go używają: SDK v2 nie instaluje go już domyślnie

Podczas uruchamiania to opcja --restart unless-stopped odróżnia wdrożenie produkcyjne od prostego testu: bez niej pierwsza awaria wyłączy serwer, dopóki ktoś tego nie zauważy.

# Budowa obrazu
docker build -t mon-mcp-server .

# Uruchomienie kontenera
docker run -d \
  --name mcp-server \
  -p 8000:8000 \
  -e MY_API_KEY="secret" \
  -e DATABASE_URL="postgresql://..." \
  --restart unless-stopped \
  mon-mcp-server

Docker Compose sprawia, że ta konfiguracja jest powtarzalna, i dodaje sprawdzanie stanu (health check), którego orkiestrator używa do wykrycia zawieszonego serwera — żywy proces, który nie odpowiada, to scenariusz, którego proste automatyczne restarty nie obejmują:

# docker-compose.yml
version: "3.8"
services:
  mcp-server:
    build: .
    ports:
      - "8000:8000"
    environment:
      - MY_API_KEY=${MY_API_KEY}
      - DATABASE_URL=${DATABASE_URL}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/"]
      interval: 30s
      retries: 3

Opcje 3 i 4: Wdrożenia zarządzane

Prefect Horizon (dawniej FastMCP Cloud), platforma od zespołu stojącego za niezależnym frameworkiem FastMCP, eliminuje etap infrastruktury: logujesz się na horizon.prefect.io za pomocą konta GitHub, wybierasz repozytorium i plik serwera, a platforma buduje i publikuje URL ze wbudowaną autentyfikacją. Jest skierowana do serwerów napisanych w tym frameworku (pip install fastmcp, from fastmcp import FastMCP), który różni się od oficjalnego SDK używanego w tym kursie; dostępny jest darmowy plan dla projektów osobistych.

Cloudflare Workers celuje w inny profil użycia: serverless, z wykonaniem jak najbliżej użytkownika, co redukuje opóźnienia. Dedykowany szablon pozwala szybko rozpocząć projekt:

# Użyj szablonu MCP od Cloudflare
npm create cloudflare@latest -- remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless

Obie opcje uwalniają Cię od zarządzania certyfikatami i restartami, kosztem zależności od platformy i ograniczeń wykonania — serverless Worker na przykład nie współgra dobrze ze serwerem stanowym.

Zabezpieczanie wdrożenia

HTTPS jest nie do negocjacji: Vibe odrzuca punkty końcowe w postaci zwykłego tekstu, a token przesyłany przez HTTP to token skompromitowany. Trzy ścieżki prowadzą do tego celu w zależności od Twojego hostingu. Odwrotny serwer proxy taki jak Nginx lub Caddy umieszczony przed Twoim serwerem, z certyfikatem Let’s Encrypt, pokrywa przypadek dedykowanego serwera. Platformy natywne dla chmury — Hugging Face, Cloudflare i większość dostawców PaaS — zapewniają HTTPS automatycznie. Tunel, taki jak Cloudflare Tunnel, udostępnia serwer pozostający w Twojej sieci wewnętrznej bez otwierania portów.

Żaden sekret nie powinien pojawiać się w kodzie. Zwróć uwagę na różnicę między poniższymi dwiema składniami: os.environ["MCP_API_TOKEN"] powoduje niepowodzenie uruchomienia, jeśli zmienna nie istnieje, co jest dokładnie pożądanym zachowaniem dla obowiązkowego sekretu, podczas gdy os.environ.get() toleruje brak wartości dla parametrów opcjonalnych.

import os

# Konfiguracja poprzez zmienne środowiskowe
API_TOKEN = os.environ["MCP_API_TOKEN"]       # Obowiązkowe
DATABASE_URL = os.environ.get("DATABASE_URL")  # Opcjonalne
DEBUG = os.environ.get("DEBUG", "false") == "true"

Publiczny serwer bez limitowania przepustowości prędzej czy później ulegnie nasyceniu, celowo lub nie. W większości przypadków wystarczy limiter oparty na adresie IP:

from fastapi import FastAPI, Request
from slowapi import Limiter, _rate_limit_exceeded_handler

limiter = Limiter(key_func=lambda request: request.client.host)
api = FastAPI()
api.state.limiter = limiter

@api.middleware("http")
async def rate_limit(request: Request, call_next):
    # 100 żądań na minutę na adres IP
    ...

Obserwacja tego, co się dzieje

W środowisku produkcyjnym nie masz już terminala przed oczami, a narzędzie, które zawodzi raz na dziesięć razy, można zdiagnozować tylko dzięki śladom (logom). Minimalnie instrumentuj dane wejściowe, wyjściowe i czas trwania każdego wywołania:

import logging
import time

logger = logging.getLogger("mcp-server")

@mcp.tool()
async def my_tool(param: str) -> str:
    """Moje narzędzie z logowaniem."""
    start = time.time()
    logger.info(f"Tool called with param={param}")

    try:
        result = await process(param)
        duration = time.time() - start
        logger.info(f"Tool finished in {duration:.2f}s")
        return result
    except Exception as e:
        logger.error(f"Error in tool: {e}")
        raise

Mierzenie czasu trwania nie jest luksusem: narzędzie, które odpowiada przez dwanaście sekund, wyzwala limity czasu po stronie klienta i sprawia wrażenie uszkodzonego serwera, podczas gdy w rzeczywistości działa. Zanim ogłosisz swój serwer, przejrzyj następujących sześć punktów konfiguracji.

  • Aktywny HTTPS i ważny certyfikat
  • Zmienne środowiskowe dla wszystkich sekretów
  • Włączone strukturalne logowanie
  • Punkt końcowy sprawdzania stanu (/ lub /health)
  • Automatyczny restart po awarii
  • Skonfigurowane limitowanie przepustowości

Pozostają dwa testy, które ludzie najczęściej pomijają, a które ujawniają prawdziwe problemy: test z MCP Inspector uruchomionym z zewnątrz, a następnie test z Mistral Vibe. Serwer, który odpowiada idealnie z Twojej maszyny, może zostać zablokowany przez zapór ogniowy lub konfigurację CORS, gdy tylko zostanie wywołany z innego miejsca.

Kluczowe wnioski

  • Hugging Face Spaces: najszybsze, darmowe, idealne na start
  • Docker: pełna kontrola, odpowiednie dla serwerów dedykowanych i chmury
  • Prefect Horizon (ex-FastMCP Cloud): wdrożenie z GitHuba, dla serwerów napisanych we frameworku FastMCP
  • Cloudflare Workers: serverless, niskie opóźnienia, skalowalność
  • Zabezpiecz za pomocą HTTPS, zmiennych środowiskowych i limitowania przepustowości
  • Dodaj monitoring i logi do debugowania w środowisku produkcyjnym