MCP con Python: conecta APIs y bases de datos a tu agente

MCP sirve para que distintos clientes descubran y llamen herramientas con un protocolo común. No convierte una función insegura en segura. Para aprender sin conectar datos de clientes, construiremos una herramienta que consulta ventas ficticias por fecha, con base de solo lectura y resultados limitados.

Descarga servidor_mcp.py. Es un programa completo: crea una base de ejemplo cuando se lo pides y, al iniciarse normalmente, expone una herramienta y un recurso por stdio. No necesita API key para crear o consultar el dataset local. El cliente de IA que conectes puede tener sus propios costes.

1. Entorno y datos reproducibles

Necesitas Python 3.10 o posterior. Guarda el archivo en una carpeta nueva y ejecuta:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install "mcp==1.30.0"
python3 servidor_mcp.py --crear-demo
python3 -c 'from servidor_mcp import ventas_por_dia; print(ventas_por_dia("2026-09-01"))'

Obtendrás dos registros: A-100 por 1250 centavos y B-200 por 500 centavos. Los importes se guardan como enteros para evitar introducir redondeos de punto flotante en esta demostración. La moneda no está definida: son datos de prueba, no una facturación real.

El comando de creación se niega a sobrescribir ventas-demo.db. Si necesitas repetir el experimento, usa otra carpeta o elimina conscientemente solo tu base ficticia. El archivo resuelve la ruta de SQLite junto a sí mismo, por lo que cambiar el directorio de trabajo del cliente no crea accidentalmente otra base vacía.

2. La herramienta de lectura

Este ejemplo fija MCP Python SDK 1.30.0, comprobado con Python 3.11.15. En esa versión, FastMCP se importa desde mcp.server.fastmcp. No ejecutes pip install mcp sin versión para este archivo: SDK 2.x renombra la clase a MCPServer y cambia APIs. Si tu proyecto ya usa v2, sigue su guía oficial de migración en vez de degradar una aplicación existente. El archivo define:

@mcp.tool()
def ventas_por_dia(fecha: str) -> list[dict]:
    """Lee hasta 100 ventas ficticias de una fecha ISO YYYY-MM-DD."""
    # La implementación completa está en el archivo descargable.

La firma permite al SDK construir el schema. Dentro de la función, el código valida que la fecha exista y esté en formato ISO estricto. Después abre SQLite con mode=ro, ejecuta una consulta parametrizada y limita la salida a 100 filas. El modelo no proporciona SQL, rutas de archivo ni nombres de tabla.

Una respuesta vacía significa “no hay ventas para esa fecha en este dataset”. Una fecha imposible, como 2026-02-30, produce un error. No conviertas ambos casos en una lista vacía: ocultarías errores del usuario o del agente.

3. Conecta el proceso al cliente

Con el entorno activo, puedes registrar el servidor local en Claude Code:

claude mcp add --transport stdio ventas-demo -- "$PWD/.venv/bin/python" "$PWD/servidor_mcp.py"
claude mcp list

En Windows, usa rutas absolutas al intérprete de .venv/Scripts/python.exe y al archivo. Revisa los permisos que solicita el cliente antes de aceptar. Pídele “consulta las ventas ficticias del 1 de septiembre de 2026” y comprueba la llamada a ventas_por_dia, sus argumentos y el resultado, no solo el texto final.

Si ejecutas python3 servidor_mcp.py directamente, puede parecer que no hace nada: espera mensajes del protocolo por entrada estándar. No imprimas logs normales en stdout durante una sesión stdio; corromperían el canal. Para diagnóstico utiliza stderr o las herramientas del cliente.

Se comprobaron la consulta SQLite, fechas inválidas, no sobrescritura, solo lectura y una sesión stdio real entre cliente y servidor del SDK 1.30.0: initialize, listado y llamada de herramienta, y lectura del recurso. No se usó un LLM. Registrar el servidor en Claude Code y ejecutar una conversación real es una comprobación adicional, no una prueba que demos por realizada en tu máquina.

4. Un recurso no es otra herramienta

El archivo también declara el esquema con el decorador correcto del servidor:

@mcp.resource("esquema://ventas")
def esquema_ventas() -> str:
    return "ventas(fecha TEXT ISO, producto TEXT, centavos INTEGER)"

El recurso ofrece contexto de lectura; la herramienta recibe una fecha y ejecuta una consulta. No uses @Resource importado como si fuera el decorador de FastMCP. Que el servidor anuncie un recurso tampoco significa que todo cliente lo cargue automáticamente: depende de sus capacidades y del flujo de interacción.

5. Si necesitas una API externa

No añadas una herramienta fetch_url(url) abierta a cualquier destino. Empieza con un contrato estrecho, como estado_pedido(id), y fija el host en configuración del servidor. Valida el ID, utiliza credenciales de mínimo privilegio, un timeout, límite de respuesta y un esquema de salida pequeño.

Prueba con un servicio de desarrollo del proveedor. Devuelve al agente estados diferenciados: no encontrado, sin permiso, timeout y dato válido. Un 200 HTTP no basta: valida la estructura de la respuesta. No incluyas tokens, cabeceras ni el cuerpo completo del error en el resultado enviado al modelo.

El ejemplo descargable no hace una llamada a una API ficticia presentada como real. Añadir un proveedor requiere su contrato, credenciales y pruebas de integración. Para un solo cliente, un function call directo puede ser más simple que MCP.

6. Pruebas y límites antes de producción

Prueba	Esperado
2026-09-01	Dos registros, 1250 y 500 centavos
2026-09-02	Lista vacía
Fecha imposible o texto SQL	Error de validación, no consulta libre
Crear la demo por segunda vez	Error, sin sobrescritura
Consultar después de mover el directorio de trabajo	Misma base junto al script
Intentar escribir usando la conexión de solo lectura	SQLite rechaza la escritura

Solo lectura no significa “sin riesgo”: puedes filtrar datos al modelo o saturar una base con consultas. Para datos reales necesitas autorización por usuario/organización antes de consultar, límites de frecuencia, retención y auditoría. El ejemplo es local, de un solo dataset, sin autenticación multiusuario. No lo publiques como servidor HTTP sin diseñar esas barreras.

Continúa con memoria y RAG si tu siguiente herramienta recuperará documentos, y con seguridad de MCP antes de conectar información sensible. El curso de instalación ofrece un runtime preparado si no quieres mantener el bucle del agente tú mismo.