Conceptos básicos del núcleo de MCP

9 ejemplos para empezar con los Conceptos básicos del núcleo de MCP: 6 básicos y 3 intermedios.

Prerrequisitos

• Python 3.10 o posterior.
• Instala el SDK oficial de Python para MCP: pip install mcp.
• Una terminal para ejecutar el servidor como un proceso local; no se requiere configuración de red para stdio.

Ejemplos básicos

1. Instalar e importar el SDK

Confirma que el SDK está instalado e importa las piezas que necesitas para un servidor mínimo.

# server.py
from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("basics-demo")

• FastMCP es la clase de servidor de alto nivel en el SDK oficial de Python, creada para definiciones rápidas de herramientas/recursos/prompts.
• La cadena que se pasa a FastMCP nombra al servidor; los clientes muestran este nombre al listar las conexiones.
• Este objeto es el único punto de entrada al que adjuntas herramientas, recursos y prompts.

2. Definir una única herramienta

Registra una única herramienta invocable usando un decorador, la forma más sencilla de exponer una función a un cliente.

@mcp.tool()
def add(a: int, b: int) -> int:
    """Suma dos números."""
    return a + b

• El decorador @mcp.tool() convierte una función ordinaria de Python en una herramienta de MCP detectable.
• Las anotaciones de tipo (a: int, b: int) se convierten automáticamente en el esquema de entrada de la herramienta.
• La cadena de documentación se convierte en la descripción de la herramienta, que el modelo lee para decidir cuándo llamarla.

Relacionado: Definición de herramientas invocables en un servidor MCP - esquema completo de herramientas y patrones de manejadores

3. Ejecutar el servidor sobre stdio

Inicia el servidor para que un cliente local pueda generarlo como un subproceso y comunicarse con él a través de la entrada y salida estándar.

if __name__ == "__main__":
    mcp.run(transport="stdio")

• transport="stdio" es el transporte más sencillo: el servidor lee las solicitudes de stdin y escribe las respuestas en stdout.
• stdio es la opción predeterminada correcta para herramientas locales que se ejecutan junto al cliente en la misma máquina.
• No se necesita configuración de puertos, TLS ni autenticación para un servidor stdio.

Relacionado: Elección entre transportes stdio y HTTP/SSE para MCP - cuándo usar un transporte remoto en su lugar

4. Conectar un cliente al servidor

Utiliza las utilidades del cliente del SDK de Python para generar el proceso del servidor y abrir una sesión.

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
 
params = StdioServerParameters(command="python", args=["server.py"])
 
async def main():
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            print("Conectado a:", session)
 
asyncio.run(main())

• StdioServerParameters indica al cliente cómo lanzar el proceso del servidor (comando más argumentos).
• stdio_client abre el subproceso y produce flujos de lectura/escritura para el protocolo.
• session.initialize() realiza el handshake de MCP antes de realizar cualquier llamada a herramientas, recursos o prompts.

5. Listar las herramientas del servidor

Pregunta al servidor conectado qué herramientas expone antes de llamar a alguna de ellas.

async with ClientSession(read, write) as session:
    await session.initialize()
    tools = await session.list_tools()
    for tool in tools.tools:
        print(tool.name, "-", tool.description)

• list_tools() realiza el descubrimiento: el cliente aprende qué está disponible sin codificar de forma rígida los nombres de las herramientas.
• Cada herramienta devuelta lleva su nombre, descripción y esquema de entrada.
• Este es el mismo paso de descubrimiento que realiza un cliente real como Claude Code cuando se conecta a tu servidor.

6. Llamar a la herramienta

Invoca la herramienta add por su nombre con los argumentos correspondientes y lee el resultado.

result = await session.call_tool("add", arguments={"a": 2, "b": 3})
print(result.content)

• call_tool envía el nombre de la herramienta y un diccionario de argumentos que coinciden con el esquema de la herramienta.
• El content de la respuesta contiene el valor de retorno de la herramienta, envuelto en el formato de contenido de MCP.
• Si los argumentos no coinciden con el esquema, el servidor devuelve un error en lugar de un resultado.

Ejemplos intermedios

7. Añadir una segunda herramienta y volver a conectar

Extiende el mismo servidor con una segunda herramienta para ver cómo coexisten múltiples herramientas en una sola sesión.

@mcp.tool()
def greet(name: str) -> str:
    """Devuelve un saludo amigable para el nombre dado."""
    return f"¡Hola, {name}!"
 
# el servidor ahora expone tanto add() como greet()

• Múltiples funciones @mcp.tool() pueden residir en la misma instancia de FastMCP; cada una se convierte en su propia entrada detectable.
• Un cliente que se reconecta (o vuelve a llamar a list_tools()) ve ambas herramientas sin ningún código de registro del lado del servidor.
• Mantener cada herramienta centrada en una sola tarea facilita y hace más fiables las decisiones de selección de herramientas del modelo.

8. Manejar un error de herramienta con gracia

Genera un error claro desde el interior del manejador de una herramienta para que el cliente y el modelo obtengan comentarios útiles en lugar de un fallo.

@mcp.tool()
def divide(a: float, b: float) -> float:
    """Divide a entre b."""
    if b == 0:
        raise ValueError("b no debe ser cero")
    return a / b

• Generar una excepción estándar de Python dentro de un manejador de herramientas es capturado por el SDK y devuelto al cliente como un error de herramienta.
• Un mensaje específico y descriptivo ayuda al modelo a decidir si debe reintentar con argumentos diferentes o rendirse.
• Permitir que las excepciones se propaguen sin ser capturadas (en lugar de fallar el proceso) mantiene el servidor disponible para la siguiente llamada.

9. Integrar el servidor en Claude Desktop

Apunta un cliente MCP real a tu servidor stdio usando su archivo de configuración, en lugar del cliente hecho a mano del ejemplo 4.

{
  "mcpServers": {
    "basics-demo": {
      "command": "python",
      "args": ["/ruta/absoluta/a/server.py"]
    }
  }
}

• Claude Desktop (y clientes similares) lanzan servidores stdio leyendo un comando y una lista de argumentos de un archivo de configuración, exactamente como StdioServerParameters.
• Usar una ruta absoluta a server.py evita problemas de directorio de trabajo cuando el cliente genera el proceso.
• Una vez configurado, el mismo código de servidor que probaste con un cliente hecho a mano ahora es invocable desde la interfaz de usuario de conversación de Claude.

Relacionado: Comparación de herramientas, recursos y prompts de MCP - decide qué exponer a continuación a medida que tu servidor crece

Relacionado

• Comprender MCP: Herramientas, Recursos y Prompts - la base conceptual de lo que acabas de construir.
• Definición de herramientas invocables en un servidor MCP - esquemas y manejadores en profundidad, más allá de una única herramienta de juguete.
• Exponer datos legibles como recursos MCP - la siguiente primitiva para añadir a este servidor.
• Mejores prácticas para los conceptos básicos del núcleo de MCP - una lista de verificación una vez que superes el prototipo de una sola herramienta.

Versiones de la pila: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y la especificación actual del Protocolo de Contexto del Modelo. Los nombres de los modelos, las versiones del SDK y la especificación de MCP cambian rápidamente: verifica los detalles actuales en platform.claude.com/docs y modelcontextprotocol.io antes de confiar en ellos.