Configuración de un servidor MCP local (STDIO)
En esta página
Actualizado el 2 de noviembre de 2026 — MCP Python SDK v2. Este curso sigue ahora la versión 2 del SDK
mcp(2.3.0 a fecha de 2 de octubre de 2026):MCPServersustituye aFastMCP, la configuración del transporte se traslada arun()ostreamable_http_app(), y una aplicación expuesta bajo un nombre de host real debe declarar dicho host (transport_security). Esta es también la versión exigida por el SDK de Mistral: el extramistralai[agents]requieremcp>=2.2.0,<3.0. Fuentes: Novedades en la v2 · Guía de migración · Despliegue y escalado.
Tu primer servidor MCP local
El modo STDIO es el punto de partida natural para desarrollar y probar un servidor MCP: todo se ejecuta en tu máquina, sin despliegues, sin URL públicas ni certificados que gestionar. Editas un archivo, reinicias y observas. En esta lección, escribirás un servidor MCP local en Python y luego lo conectarás a un cliente.
En cuanto a los prerequisitos, necesitas Python 3.10 o superior, un pip actualizado y, preferiblemente, un entorno virtual dedicado. Este último punto no es cosmético: los paquetes de MCP evolucionan rápidamente y un entorno virtual separado por proyecto evita que rompas un servidor funcional al instalar una dependencia para otro.
# Crear un entorno virtual
python -m venv mcp-env
source mcp-env/bin/activate # Linux/Mac
# mcp-env\Scripts\activate # Windows
# SDK oficial de MCP (v2) y SDK de Mistral con su extra de agentes
pip install "mcp[cli]>=2.2,<3" "mistralai[agents]"
Escritura del servidor
Con MCPServer, la clase de alto nivel del SDK oficial (anteriormente FastMCP), un servidor local requiere apenas unas pocas líneas. Instancias una aplicación asignándole un nombre descriptivo y luego decoras tus funciones de Python con @app.tool() para exponerlas.
# serveur_local.py
from mcp.server.mcpserver import MCPServer
# Inicializar el servidor con un nombre descriptivo
app = MCPServer("Local Demo Server")
@app.tool()
def greet(name: str) -> str:
"""Saluda a una persona por su nombre.
Args:
name: El nombre de pila de la persona a saludar
Returns:
Un mensaje de saludo personalizado
"""
return f"Hello {name}! Welcome to the world of MCP."
@app.tool()
def calculate(operation: str, a: float, b: float) -> str:
"""Realiza un cálculo matemático simple.
Args:
operation: La operación a realizar (add, sub, mul, div)
a: Primer número
b: Segundo número
Returns:
El resultado del cálculo
"""
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}"
Este archivo expone dos herramientas. Observa el papel de las cadenas de documentación (docstrings): no solo documentan tu código para un colega; se convierten literalmente en la descripción que lee el modelo para decidir si invocar calculate en lugar de greet. Una docstring descuidada aquí provocará llamadas erráticas más adelante.
Configuración del cliente STDIO
En el lado del cliente, no te conectas a una dirección; explicas cómo iniciar el servidor. Esa es la función de StdioServerParameters.
# client_stdio.py
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
from pathlib import Path
# Ruta a tu servidor
path_to_server = Path("serveur_local.py")
# Configuración del servidor STDIO
server_params = StdioServerParameters(
command="python", # El comando para lanzar el servidor
args=[str(path_to_server)], # Los argumentos (el archivo Python)
env=None, # Variables de entorno (opcional)
)
# Crear el cliente MCP
mcp_client = MCPClientSTDIO(stdio_params=server_params)
Tres parámetros merecen detalle.
command
Este es el comando del sistema que lanza el proceso del servidor: "python" para un servidor en Python, "node" para uno en JavaScript, o la ruta directa a un binario si tu servidor está compilado.
# Python
command="python"
# Node.js
command="node"
# Un ejecutable compilado
command="./mon_serveur_mcp"
args
Esta es la lista de argumentos que se pasan a dicho comando. Para un script de Python, esto es como mínimo la ruta del archivo, pero nada te impide pasar aquí las opciones de tu servidor.
# Script simple
args=["serveur_local.py"]
# Con argumentos adicionales
args=["serveur_local.py", "--port", "8080", "--verbose"]
env
Este es el diccionario de variables de entorno que se pasan al proceso del servidor: el canal mediante el cual le entregas una clave de API, una URL de base de datos o una bandera de depuración.
import os
server_params = StdioServerParameters(
command="python",
args=["serveur_local.py"],
env={
**os.environ, # Heredar del entorno actual
"API_KEY": "your_api_key",
"DATABASE_URL": "postgresql://...",
"DEBUG": "true",
},
)
El comportamiento de este parámetro suele sorprender. Con env=None, el servidor hereda todo el entorno del proceso padre; con un diccionario, ve estrictamente solo las variables listadas. Si proporcionas un diccionario sin volcar os.environ en él, no te sorprendas si tu servidor ya no puede encontrar su PATH o tu clave de API: el comportamiento es perfectamente lógico, simplemente radical.
Pruebas antes de la integración
Antes de conectar tu servidor a un agente, pruébalo de forma aislada con el MCP Inspector. El razonamiento es simple: si una llamada falla una vez conectado el servidor al modelo, no sabrás si el problema reside en tu código o en la decisión del modelo. El Inspector elimina esta ambigüedad.
npx @modelcontextprotocol/inspector python serveur_local.py
El comando abre una interfaz web local donde puedes listar las herramientas expuestas, inspeccionar la descripción y los parámetros que recibirá el modelo, desencadenar una llamada manual con argumentos de tu elección y verificar el formato exacto del valor de retorno. Acostúmbrate a usarlo sistemáticamente: son cinco minutos que te ahorran una hora.
Finalmente, aquí tienes una organización de archivos que envejece bien, con el servidor, el cliente, las dependencias, los secretos mantenidos fuera del repositorio y pruebas unitarias para tus herramientas:
mon-projet-mcp/
├── serveur_local.py # El servidor MCP
├── client_stdio.py # El script del cliente
├── requirements.txt # Dependencias
├── .env # Variables de entorno (nunca confirmar)
└── tests/
└── test_tools.py # Pruebas unitarias de las herramientas
Puntos clave
- Un servidor STDIO se lanza como un proceso local
StdioServerParametersconfigura el comando, los argumentos y las variables de entorno- Las docstrings de tus herramientas sirven de descripción para el modelo
- El MCP Inspector (
npx @modelcontextprotocol/inspector) es esencial para las pruebas env=Nonehereda todo el entorno; un diccionario explícito limita las variables