Ir al contenido principal
Español— Elegir un idioma
Menú

Arquitectura de un servidor MCP personalizado

Lección 10 de 14 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Diseño de un servidor MCP para producción
  2. Elección del framework
  3. Una estructura de proyecto duradera
  4. El punto de entrada: server.py
  5. Un módulo de herramientas por dominio
  6. Configuración centralizada
  7. Errores legibles por el modelo
  8. Con estado o sin estado
  9. Puntos clave

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): MCPServer sustituye a FastMCP, la configuración del transporte se traslada a run() o streamable_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 que requiere el SDK de Mistral: el extra mistralai[agents] necesita mcp>=2.2.0,<3.0. Fuentes: Novedades en la v2 · Guía de migración · Despliegue y escalado.

Diseño de un servidor MCP para producción

Un prototipo MCP cabe en un archivo de cuarenta líneas, y a menudo eso basta para convencer a un equipo. Sin embargo, pasar al uso real lo cambia todo: varias personas llaman al servidor, las herramientas se multiplican, la configuración varía según el entorno y ese único archivo se vuelve imposible de mantener. Esta lección aborda las decisiones arquitectónicas que evitan chocar contra ese muro: elección del framework, estructuración del proyecto, gestión de la configuración y los errores, y la decisión entre servidores con estado y sin estado.

Elección del framework

En Python, la clase MCPServer del SDK oficial (anteriormente FastMCP) es la herramienta estándar. Expone una API basada en decoradores y gestiona el protocolo MCP por ti, de modo que un servidor cobra vida en tres líneas:

from mcp.server.mcpserver import MCPServer

app = MCPServer(
    "Mi Servidor",
    instructions="Servidor MCP para gestión de proyectos",
)

Los equipos de JavaScript y TypeScript cuentan con el SDK oficial de MCP publicado por Anthropic. La lógica es comparable aunque la sintaxis difiera:

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

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

La elección depende menos de las capacidades y más del ecosistema desde el que tu servidor obtendrá sus datos. Un servidor que consulta una base de datos mediante SQLAlchemy o reutiliza scripts de procesamiento existentes será naturalmente en Python; un servidor respaldado por una aplicación Express existente permanecerá en TypeScript. La siguiente tabla resume las diferencias prácticas.

CriterioMCPServer (SDK de Python)SDK de MCP (TypeScript)
MadurezMuy maduroMaduro
Decoradores@app.tool()Método server.tool()
Transporte HTTPIntegrado (FastAPI)Integrado (Express)
ComunidadAmpliaAmplia

Una estructura de proyecto duradera

La estructura de directorios recomendada separa cuatro responsabilidades: lo que ve el modelo (tools/), lo que accede a los datos (services/), lo que controla el acceso (auth/) y lo que describe el entorno (config.py, .env).

my-mcp-server/
├── server.py              # Punto de entrada FastAPI + montaje MCP
├── tools/
│   ├── __init__.py
│   ├── project_tools.py   # Herramientas de gestión de proyectos
│   ├── file_tools.py      # Herramientas de gestión de archivos
│   └── search_tools.py    # Herramientas de búsqueda
├── services/
│   ├── __init__.py
│   ├── database.py        # Acceso a base de datos
│   └── external_api.py    # Llamadas a API externas
├── auth/
│   ├── __init__.py
│   └── middleware.py       # Middleware de autenticación
├── config.py              # Configuración (variables de entorno)
├── Dockerfile             # Contenerización
├── requirements.txt       # Dependencias de Python
├── .env                   # Variables de entorno (no confirmar)
└── tests/
    ├── test_tools.py
    └── test_integration.py

Esta separación tiene una consecuencia directa y concreta: tus herramientas ya no contienen llamadas SQL ni HTTP, solo validación y delegación a un servicio. Así puedes probar la lógica de negocio sin pasar por MCP y cambiar de base de datos sin tocar ni una sola cadena de documentación que vea el modelo.

El punto de entrada: server.py

El archivo principal no hace más que ensamblar componentes: crea la aplicación FastAPI, apila los middlewares y monta cada servidor MCP en su propia ruta.

# server.py
"""Punto de entrada del servidor MCP."""

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

# Cada servidor MCP debe iniciar su gestor de sesiones
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
        yield

# Aplicación FastAPI
api = FastAPI(
    title="Mi Servidor MCP",
    version="1.0.0",
    lifespan=lifespan,
)

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

# Middleware de autenticación
api.add_middleware(AuthMiddleware)

# Nombre de host público bajo el que se sirven los servidores (de lo contrario: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])

# Montar servidores MCP en rutas distintas
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))

# Página de inicio (opcional pero útil)
@api.get("/")
async def root():
    return {
        "service": "Mi Servidor MCP",
        "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)

Montar en rutas distintas permite a los usuarios habilitar solo el dominio que necesitan: alguien que busque documentación se conecta a /search/mcp sin que se le ofrezcan herramientas de gestión de proyectos. En cuanto a la página de inicio, parece trivial hasta que un colega pregunta por la URL exacta del punto final; responde por ti y sirve como comprobación de estado.

Un módulo de herramientas por dominio

Cada archivo en la carpeta tools/ declara su propio objeto MCPServer y agrupa herramientas del mismo dominio funcional. Así es como se ve el módulo de gestión de proyectos, importado anteriormente por server.py:

# tools/project_tools.py
"""Herramientas MCP para gestión de proyectos."""

from mcp.server.mcpserver import MCPServer
from services.database import db

project_mcp = MCPServer(
    "Gestor de Proyectos",
    instructions="Herramientas para gestión de proyectos y tareas",
)

@project_mcp.tool()
async def create_project(name: str, description: str = "") -> str:
    """Crea un nuevo proyecto.

    Args:
        name: Nombre del proyecto (2-100 caracteres)
        description: Descripción del proyecto (opcional)

    Returns:
        JSON con los detalles del proyecto creado
    """
    project = await db.projects.create(name=name, description=description)
    return project.to_json()

@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
    """Lista proyectos por estado.

    Args:
        status: Filtrar por estado: active, archived, all (predeterminado: active)

    Returns:
        JSON con la lista de proyectos
    """
    projects = await db.projects.list(status=status)
    return projects.to_json()

Observa lo breves que son los cuerpos de las funciones: solo dos líneas cada uno, porque el acceso a los datos reside en services/database.py. La herramienta simplemente describe su contrato al modelo y delega.

Configuración centralizada

Cualquier valor que cambie entre tu máquina y el servidor de producción debe provenir del entorno, nunca del código. Un único archivo config.py reúne estas variables con sus valores predeterminados:

# config.py
"""Configuración del servidor MCP."""

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

El parámetro max_results ilustra el beneficio de este enfoque: el día que una herramienta devuelva demasiados resultados y sature el contexto del modelo, ajustas una variable de entorno y reinicias, sin necesidad de volver a desplegar código.

Errores legibles por el modelo

Una excepción de Python que asciende abruptamente no le dice nada al modelo: ve un fallo sin entender por qué, y a menudo reintenta idénticamente. En su lugar, estandariza un formato de respuesta de error explícito con un código y un mensaje.

import json

def error_response(message: str, code: str = "error") -> str:
    """Formatea un mensaje de error estandarizado."""
    return json.dumps({
        "success": False,
        "error": {"code": code, "message": message}
    }, ensure_ascii=False)

@project_mcp.tool()
async def get_project(project_id: str) -> str:
    """Recupera los detalles de un proyecto por ID."""
    try:
        project = await db.projects.get(project_id)
        if not project:
            return error_response(f"Proyecto {project_id} no encontrado", "not_found")
        return project.to_json()
    except Exception as e:
        return error_response(f"Error del servidor: {str(e)}", "server_error")

La diferencia es decisiva en la conversación. Ante not_found, el modelo entiende que primero debe listar los proyectos para encontrar el ID correcto; ante una excepción silenciosa, se rinde o entra en bucle.

Con estado o sin estado

Un servidor con estado retiene información entre llamadas: base de datos en memoria, sesiones de usuario, contexto de trabajo. Esto es común en servidores de gestión, como el gestor de tareas de la lección anterior. Un servidor sin estado gestiona cada solicitud de forma independiente, sin recordar nada; se recomienda para cómputo o transformación puros y permite el escalado horizontal, ya que cualquier instancia puede manejar cualquier solicitud. El SDK v2 habilita esto mediante un parámetro de la aplicación HTTP (ya no se pasa al constructor). Ten en cuenta que, con la especificación del 28-07-2026, el protocolo en sí ya no conoce las sesiones: esta configuración solo afecta a los clientes que negocian una versión anterior del protocolo.

app = MCPServer("Servidor sin estado")

# La configuración se pasa al construir la aplicación HTTP
mcp_app = app.streamable_http_app(stateless_http=True)

Decide esta cuestión antes de escribir tus herramientas, no después: pasar de un servidor con estado a uno sin estado implica mover todo el estado a una base de datos externa, lo que reescribe una buena parte del código.

Puntos clave

  • Separa tus herramientas en módulos temáticos dentro de una carpeta tools/
  • Usa FastAPI como base HTTP, monta los servidores MCP en rutas dedicadas y pasa su ciclo de vida (lifespan)
  • Centraliza la configuración mediante variables de entorno
  • Estandariza los formatos de respuesta de error para que el modelo pueda utilizarlos
  • Elige entre con estado (gestión de datos) y sin estado (cómputo puro)
  • Añade una página de inicio / para documentar tus puntos finales de MCP