¿Qué es MCP y por qué necesitas un plugin personalizado?

El Model Context Protocol (MCP) es el estándar que permite a los asistentes de IA, como Claude o cualquier cliente compatible, conectarse directamente a tus herramientas, bases de datos o APIs. Piensa en un plugin MCP como un puente personalizado: le dices al asistente qué puede hacer (por ejemplo, buscar en tu base de clientes, enviar un correo o ejecutar un script) y él lo ejecuta por ti. Hasta ahora, crear estos plugins podía ser un dolor de cabeza con protocolos complejos. Pero con FastMCP, un framework minimalista para Python, puedes tener tu primer plugin funcionando en menos de 30 minutos. En esta guía, te llevaré desde cero hasta un plugin funcional que responde a comandos reales.

Tip: Antes de empezar, asegúrate de tener Python 3.9+ instalado. Puedes verificarlo con python --version. Si no lo tienes, descárgalo de python.org.

Paso 1: Instalar FastMCP y configurar tu entorno

Lo primero es preparar el terreno. FastMCP es una librería que abstrae toda la complejidad del protocolo MCP. Solo necesitas definir funciones normales de Python y decorarlas con @mcp.tool() para que el asistente las vea como herramientas disponibles.

Abre tu terminal y crea un directorio para el proyecto:

BASHmkdir mi-primer-plugin-mcp

cd mi-primer-plugin-mcp

python -m venv venv

source venv/bin/activate # En Windows: venv\Scripts\activate

Luego instala FastMCP y el servidor de transporte estándar:

BASHpip install fastmcp mcp

FastMCP maneja por debajo la comunicación con el cliente (por ejemplo, Claude Desktop o cualquier app que soporte MCP). No necesitas tocar nada de HTTP, WebSockets ni JSON-RPC manualmente. Todo se reduce a escribir funciones Python.

Paso 2: Escribe tu primer plugin con una herramienta útil

Vamos a crear un plugin que tenga dos herramientas: una para sumar dos números (simple pero ilustrativa) y otra para obtener la hora actual del sistema. Esto te mostrará cómo pasar parámetros y devolver datos estructurados.

Crea un archivo llamado plugin.py y pega el siguiente código:

PYTHONfrom fastmcp import FastMCP

from datetime import datetime

Crear una instancia del servidor MCP

mcp = FastMCP("Mi Primer Plugin")

@mcp.tool()

def sumar(a: int, b: int) -> int:

"""Suma dos números enteros y devuelve el resultado."""

return a + b

@mcp.tool()

def hora_actual(formato: str = "24h") -> str:

"""Devuelve la hora actual del sistema.

Args:

formato: "24h" para formato 24 horas, "12h" para formato AM/PM.

"""

ahora = datetime.now()

if formato == "12h":

return ahora.strftime("%I:%M:%S %p")

return ahora.strftime("%H:%M:%S")

Punto de entrada para ejecutar el servidor

if __name__ == "__main__":

mcp.run()

Explicación rápida:

• FastMCP("Mi Primer Plugin") crea el servidor con un nombre identificativo.
• Cada @mcp.tool() convierte una función en una herramienta que el asistente puede llamar.
• Los tipos de los parámetros (int, str) y el docstring son importantes: el asistente los usa para entender qué espera la función.
• mcp.run() inicia el servidor en modo estándar (por defecto usa stdio, ideal para integración local).

Paso 3: Conectar el plugin a un cliente MCP (Claude Desktop)

Ahora que tienes el servidor listo, necesitas decirle a un cliente MCP (como Claude Desktop) que lo use. El método más directo es mediante el archivo de configuración del cliente.

Para Claude Desktop, abre (o crea) el archivo de configuración en:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Añade la siguiente entrada (ajusta la ruta a tu plugin.py):

JSON{

"mcpServers": {

"mi-primer-plugin": {

"command": "python",

"args": ["/ruta/completa/a/tu/proyecto/plugin.py"]

}

}

}

Si estás en Windows, asegúrate de usar la ruta completa con barras invertidas escapadas (\\) o barras normales. Guarda el archivo y reinicia Claude Desktop.

Verás que Claude ahora tiene acceso a las herramientas "sumar" y "hora_actual". Puedes probar pidiéndole: "Usa tu plugin para sumar 15 y 27" o "¿Qué hora es en formato 12 horas?".

PROMPTClaude, usando tu plugin 'Mi Primer Plugin', calcula la suma de 1234 y 5678, y luego dime la hora actual en formato 12 horas.

El asistente llamará a las funciones sumar(1234, 5678) y hora_actual("12h") secuencialmente y te devolverá los resultados.

Paso 4: Mejora tu plugin con herramientas más complejas y manejo de errores

Ya tienes lo básico. Ahora vamos a añadir una herramienta que busque en una lista simulada de contactos. Esto te enseñará a devolver diccionarios y listas, y cómo manejar errores de forma elegante.

Actualiza tu plugin.py añadiendo lo siguiente antes de mcp.run():

PYTHON# Datos simulados de contactos

CONTACTOS = [

{"nombre": "Ana López", "email": "ana@ejemplo.com", "telefono": "555-1234"},

{"nombre": "Carlos Ruiz", "email": "carlos@ejemplo.com", "telefono": "555-5678"},

{"nombre": "María García", "email": "maria@ejemplo.com", "telefono": "555-9012"},

]

@mcp.tool()

def buscar_contacto(nombre: str) -> dict:

"""Busca un contacto por nombre exacto.

Args:

nombre: Nombre completo del contacto (ej: 'Ana López').

Returns:

Diccionario con los datos del contacto o un mensaje de error.

"""

for contacto in CONTACTOS:

if contacto["nombre"].lower() == nombre.lower():

return contacto

# Si no se encuentra, devolvemos un diccionario con el error

return {"error": f"Contacto '{nombre}' no encontrado. Contactos disponibles: {', '.join(c['nombre'] for c in CONTACTOS)}"}

@mcp.tool()

def listar_contactos() -> list:

"""Devuelve la lista completa de contactos disponibles."""

return CONTACTOS

Observa cómo manejamos el error: devolvemos un diccionario con una clave "error". El asistente leerá esto y te informará adecuadamente. No uses excepciones de Python crudas, porque el asistente no sabe interpretarlas bien. Siempre devuelve datos estructurados.

Ahora tu plugin tiene 4 herramientas. Puedes probar en Claude: "Lista todos los contactos", "Busca a María García", "Intenta buscar a Juan Pérez".

Tip: Siempre que devuelvas datos, hazlo en tipos estándar de Python (dict, list, str, int, float, bool). El protocolo MCP los serializa automáticamente a JSON. Evita devolver objetos complejos o clases personalizadas sin serializar.

Conclusión y próximos pasos

En menos de 50 líneas de código y 20 minutos, has creado un plugin MCP completamente funcional con Python y FastMCP. Has aprendido a instalar el entorno, definir herramientas con parámetros tipados, conectar el servidor a un cliente como Claude Desktop, y manejar errores de forma robusta. La belleza de este enfoque es que puedes escalarlo a cualquier cosa: desde consultas a bases de datos SQL, llamadas a APIs REST, ejecución de scripts de sistema, hasta integraciones con servicios cloud como AWS o Google Sheets. El límite lo pone tu imaginación (y las APIs que quieras conectar).

Para profundizar, te recomiendo leer la documentación oficial de FastMCP en GitHub (busca "fastmcp") y explorar conceptos como recursos (para exponer datos que el asistente pueda leer sin ejecutar herramientas) y prompts dinámicos. ¡Ahora ve y construye algo útil!

ConceptoDescripciónEjemplo en código

Herramienta (Tool)Función que el asistente puede invocar bajo demanda@mcp.tool()

Parámetros tipadosDefinen qué datos espera la herramientaa: int, nombre: str

DocstringDescripción que el asistente lee para entender la herramienta"""Suma dos números..."""

ServidorInstancia que gestiona la conexión con el clienteFastMCP("nombre")

TransporteCómo se comunican cliente y servidor (por defecto stdio)mcp.run()

Recuerda: el archivo de configuración JSON es la clave para que tu cliente (Claude Desktop, etc.) descubra y use tu plugin. Sin él, el asistente no sabrá que existe tu servidor. ¡Feliz codificación!