Configurați un server MCP local (STDIO)
Pe această pagină
Actualizat pe 2 noiembrie 2026 — MCP Python SDK v2. Acest curs urmează acum versiunea 2 a SDK-ului
mcp(2.3.0 la data de 2 octombrie 2026):MCPServerînlocuieșteFastMCP, setările de transport se mută înrun()saustreamable_http_app(), iar o aplicație expusă sub un nume de gazdă real trebuie să declare acel nume de gazdă (transport_security). Aceasta este, de asemenea, versiunea cerută de Mistral SDK: extra-ulmistralai[agents]necesitămcp>=2.2.0,<3.0. Surse: Ce este nou în v2 · Ghid de migrare · Deploy & scale.
Primul dumneavoastră server MCP local
Modul STDIO este punctul de plecare natural pentru dezvoltarea și testarea unui server MCP: totul rulează pe mașina dumneavoastră, fără deploy, fără URL public și fără certificate de gestionat. Editați un fișier, reporniți și observați. În această lecție, veți scrie un server MCP local în Python și apoi îl veți conecta la un client.
În ceea ce privește prerechizitele, aveți nevoie de Python 3.10 sau o versiune superioară, de un pip actualizat și, de preferință, de un mediu virtual dedicat. Ultimul punct nu este doar cosmetic: pachetele MCP evoluează rapid, iar un venv separat per proiect vă împiedică să stricați un server funcțional atunci când instalați o dependență pentru altul.
# Crearea unui mediu virtual
python -m venv mcp-env
source mcp-env/bin/activate # Linux/Mac
# mcp-env\Scripts\activate # Windows
# SDK-ul oficial MCP (v2) și Mistral SDK cu extra-ul său pentru agenți
pip install "mcp[cli]>=2.2,<3" "mistralai[agents]"
Scrierea serverului
Cu MCPServer, clasa de nivel înalt din SDK-ul oficial (fostul FastMCP), un server local necesită doar câteva linii de cod. Instanțiați o aplicație oferindu-i un nume descriptiv, apoi decorați funcțiile Python cu @app.tool() pentru a le expune.
# serveur_local.py
from mcp.server.mcpserver import MCPServer
# Inițializarea serverului cu un nume descriptiv
app = MCPServer("Local Demo Server")
@app.tool()
def greet(name: str) -> str:
"""Greets a person by name.
Args:
name: The first name of the person to greet
Returns:
A personalized greeting message
"""
return f"Hello {name}! Welcome to the world of MCP."
@app.tool()
def calculate(operation: str, a: float, b: float) -> str:
"""Performs a simple mathematical calculation.
Args:
operation: The operation to perform (add, sub, mul, div)
a: First number
b: Second number
Returns:
The result of the calculation
"""
ops = {
"add": a + b,
"sub": a - b,
"mul": a * b,
"div": a / b if b != 0 else "Error: division by zero"
}
result = ops.get(operation, "Unknown operation")
return f"{a} {operation} {b} = {result}"
Acest fișier expune două instrumente. Observați rolul docstring-urilor: ele nu doar documentează codul pentru un coleg; ele devin literalmente descrierea pe care modelul o citește pentru a decide dacă să apeleze calculate în loc de greet. Un docstring neglijent aici duce la apeluri eronatice mai târziu.
Configurarea clientului STDIO
Din partea clientului, nu vă conectați la o adresă; explicați cum să porniți serverul. Acesta este rolul lui StdioServerParameters.
# client_stdio.py
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
from pathlib import Path
# Calea către serverul dumneavoastră
path_to_server = Path("serveur_local.py")
# Configurarea serverului STDIO
server_params = StdioServerParameters(
command="python", # Comanda pentru lansarea serverului
args=[str(path_to_server)], # Argumentele (fișierul Python)
env=None, # Variabile de mediu (opțional)
)
# Crearea clientului MCP
mcp_client = MCPClientSTDIO(stdio_params=server_params)
Trei parametri merită detalii suplimentare.
command
Aceasta este comanda de sistem care lansează procesul serverului: "python" pentru un server Python, "node" pentru un server JavaScript sau calea directă către un binar dacă serverul dumneavoastră este compilat.
# Python
command="python"
# Node.js
command="node"
# Un executabil compilat
command="./mon_serveur_mcp"
args
Aceasta este lista de argumente transmise acelei comenzi. Pentru un script Python, acesta este cel puțin calea fișierului, dar nimic nu vă împiedică să transmiteți aici opțiunile serverului dumneavoastră.
# Script simplu
args=["serveur_local.py"]
# Cu argumente suplimentare
args=["serveur_local.py", "--port", "8080", "--verbose"]
env
Acesta este dicționarul de variabile de mediu transmise procesului serverului: canalul prin care îi transmiteți o cheie API, un URL de bază de date sau un flag de depanare.
import os
server_params = StdioServerParameters(
command="python",
args=["serveur_local.py"],
env={
**os.environ, # Moștenire din mediul curent
"API_KEY": "your_api_key",
"DATABASE_URL": "postgresql://...",
"DEBUG": "true",
},
)
Comportamentul acestui parametru surprinde adesea oamenii. Cu env=None, serverul moștenește întregul mediul procesului părinte; cu un dicționar, vede strict doar variabilele listate. Dacă furnizați un dicționar fără a turna os.environ în el, nu fiți surprins dacă serverul dumneavoastră nu mai poate găsi PATH-ul sau cheia API: comportamentul este perfect logic, pur și simplu radical.
Testați înainte de integrare
Înainte de a conecta serverul la un agent, testați-l izolat cu MCP Inspector. Raționamentul este simplu: dacă un apel eșuează odată ce serverul este conectat la un model, nu veți ști dacă problema stă în codul dumneavoastră sau în decizia modelului. Inspectorul elimină această ambiguitate.
npx @modelcontextprotocol/inspector python serveur_local.py
Comanda deschide o interfață web locală unde puteți lista instrumentele expuse, inspecta descrierea și parametrii pe care modelul îi va primi, declanșa un apel manual cu argumente la alegerea dumneavoastră și verifica formatul exact al valorii returnate. Faceți din aceasta o obișnuință sistematică: sunt cinci minute care economisesc o oră.
În final, iată o organizare a fișierelor care rezistă testului timpului, cu serverul, clientul, dependențele, secretele ținute în afara repository-ului și teste unitare pentru instrumentele dumneavoastră:
mon-projet-mcp/
├── serveur_local.py # Serverul MCP
├── client_stdio.py # Scriptul client
├── requirements.txt # Dependențe
├── .env # Variabile de mediu (niciodată comitate)
└── tests/
└── test_tools.py # Teste unitare pentru instrumente
Puncte cheie
- Un server STDIO se lansează ca un proces local
StdioServerParametersconfigurează comanda, argumentele și variabilele de mediu- Docstring-urile instrumentelor dumneavoastră servesc drept descriere pentru model
- MCP Inspector (
npx @modelcontextprotocol/inspector) este esențial pentru testare env=Nonemoștenește întregul mediu; un dicționar explicit limitează variabilele