Introducción

Conectar MCP a un agente de IA significa darle una forma controlada de descubrir y utilizar capacidades que residen fuera del modelo. El modelo no ejecuta directamente una consulta a una base de datos, no lee un archivo privado ni llama a una API empresarial. En su lugar, un cliente MCP dentro del agente se conecta a un servidor MCP, obtiene las definiciones de sus herramientas, se las envía al modelo como capacidades disponibles y ejecuta la llamada a herramienta que el modelo selecciona.

Esta separación establece un límite importante. El modelo se encarga de interpretar la solicitud del usuario y proponer el nombre de una herramienta con argumentos estructurados. El cliente MCP se encarga de mantener la sesión del protocolo, invocar la herramienta seleccionada, devolver el resultado e informar de los errores. Por tanto, un flujo de trabajo fiable consta de tres etapas distintas: descubrimiento, selección e invocación. El mismo patrón funciona tanto si el modelo está alojado en una API comercial, en un modelo autohospedado o en un framework interno para agentes.

MCP no elimina la necesidad de seguridad a nivel de aplicación. Un agente debe conectarse solo a servidores de confianza, aplicar autenticación cuando sea necesario, validar los permisos del usuario y evitar aprobar automáticamente operaciones peligrosas. La descripción de una herramienta ayuda al modelo a elegir una capacidad, pero no constituye una política de seguridad.

El flujo de trabajo del agente

Al iniciarse, el cliente MCP abre una conexión de transporte con el servidor e inicializa una sesión MCP. Después, el cliente llama a la operación de descubrimiento de herramientas del protocolo. La respuesta contiene nombres de herramientas, descripciones y esquemas de entrada. Estos esquemas describen los argumentos que acepta cada herramienta, de modo que el agente puede proporcionar al modelo información estructurada en lugar de un párrafo informal.

El modelo utiliza las definiciones descubiertas junto con la solicitud del usuario. Por ejemplo, si el servidor ofrece las herramientas search_documents y create_ticket, una solicitud para encontrar un informe de incidentes normalmente debería generar una llamada a search_documents, no a create_ticket. La salida del modelo debe tratarse como una propuesta de llamada a herramienta que contiene un nombre y argumentos. La aplicación anfitriona aún debe verificar que la herramienta se haya descubierto y que los argumentos cumplan las políticas locales antes de invocarla.

Tras la validación, el cliente MCP llama a la herramienta seleccionada y recibe contenido estructurado, texto o un error. La aplicación anfitriona puede devolver ese resultado al modelo para que genere una respuesta final en lenguaje natural. Un agente de varios pasos repite el ciclo cuando el resultado de la primera herramienta aporta información necesaria para una segunda. La aplicación debe imponer límites al número de pasos, al tiempo de ejecución y a las operaciones sensibles para evitar bucles incontrolados.

Un cliente MCP mínimo

El siguiente programa en Python demuestra el descubrimiento, la selección y la invocación mediante Streamable HTTP. Utiliza las interfaces oficiales del cliente MCP para Python para gestionar una sesión de cliente y el transporte. Instala el paquete MCP para Python en el entorno que ejecuta el agente y sustituye la URL por la de un servidor MCP que ya esté en ejecución y configurado para aceptar este transporte.

import argparse
import asyncio
import json

from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client


async def run(url: str, tool_name: str, arguments: dict) -> None:
    async with streamable_http_client(url) as streams:
        read_stream, write_stream, _ = streams

        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            discovered = await session.list_tools()

            print("Discovered tools:")
            for tool in discovered.tools:
                description = tool.description or "No description"
                print(f"- {tool.name}: {description}")

            selected = next(
                (tool for tool in discovered.tools if tool.name == tool_name),
                None,
            )
            if selected is None:
                available = ", ".join(tool.name for tool in discovered.tools)
                raise ValueError(
                    f"Unknown tool '{tool_name}'. Available tools: {available}"
                )

            print(f"Invoking {selected.name} with {json.dumps(arguments)}")
            result = await session.call_tool(
                selected.name,
                arguments=arguments,
            )
            print("Tool result:")
            if hasattr(result, "model_dump_json"):
                print(result.model_dump_json(indent=2))
            else:
                print(result)


def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument("url", help="MCP Streamable HTTP endpoint")
    parser.add_argument("tool", help="Discovered tool name to invoke")
    parser.add_argument(
        "--arguments",
        default="{}",
        help="JSON object containing tool arguments",
    )
    args = parser.parse_args()

    try:
        arguments = json.loads(args.arguments)
    except json.JSONDecodeError as error:
        raise SystemExit(f"Arguments must be valid JSON: {error}") from error

    if not isinstance(arguments, dict):
        raise SystemExit("Arguments must be a JSON object")

    try:
        asyncio.run(run(args.url, args.tool, arguments))
    except Exception as error:
        raise SystemExit(f"MCP request failed: {error}") from error


if __name__ == "__main__":
    main()

La entrada consta de un endpoint MCP, el nombre de una herramienta y un objeto JSON de argumentos. Primero, el programa imprime las herramientas devueltas por el descubrimiento y, después, comprueba que el nombre solicitado esté realmente presente. Esta comprobación es importante porque un modelo puede inventar un nombre de herramienta o conservar un nombre obsoleto de una sesión anterior. La salida incluye el resultado del servidor, que el agente puede devolver al modelo para su interpretación.

Conectar el descubrimiento con la selección del modelo

Un agente de producción coloca un adaptador de modelo entre el descubrimiento y la invocación. Después de que `list_tools` devuelva los resultados, el host convierte el nombre, la descripción y el esquema de entrada de cada herramienta al formato de llamadas a herramientas del proveedor del modelo. El formato exacto de la solicitud depende de la API del modelo, por lo que el cliente MCP no debe asumir que todos los proveedores utilizan la misma estructura de mensajes. El agente recibe la respuesta del modelo, extrae el nombre propuesto y los argumentos JSON, y realiza una validación local antes de llamar a `session.call_tool`.

El host debe rechazar una llamada a una herramienta cuando el nombre no figure en la respuesta de descubrimiento actual, los argumentos no sean un objeto, falten campos obligatorios o un valor infrinja la política de la aplicación. La validación del esquema es útil, pero las comprobaciones de autorización deben realizarse por separado. Por ejemplo, una llamada válida a `delete_record` puede seguir estando prohibida para un usuario con acceso de solo lectura. También es apropiado solicitar confirmación para acciones irreversibles, operaciones financieras, mensajes externos o cambios en datos de producción.

Después de la invocación, el resultado puede añadirse a la conversación con el modelo como un mensaje de resultado de herramienta. A continuación, el modelo puede resumir el resultado o decidir si necesita otra herramienta permitida. Conserva el resultado sin procesar para los registros, pero redacta las credenciales, los datos personales y los diagnósticos internos antes de enviar el contenido a un modelo de terceros.

Fallos comunes y prácticas fiables

Un fallo de conexión suele significar que el endpoint es incorrecto, el servidor no está disponible, el transporte no coincide o falta la autenticación. Confirma que el servidor admita el transporte seleccionado y que la red, el proxy y la configuración de TLS permitan la conexión. No resuelvas un problema de transporte recurriendo silenciosamente a un protocolo desconocido; especifica el transporte configurado y comunica el error original.

Se produce un error de herramienta desconocida cuando el agente invoca un nombre que no se devolvió durante el paso de descubrimiento actual. Actualiza el descubrimiento cuando puedan cambiar las sesiones o las capacidades del servidor y compara siempre el nombre solicitado con el conjunto actual de herramientas. Los argumentos no válidos suelen deberse a propiedades obligatorias ausentes, tipos incorrectos o a que el modelo devuelve JSON codificado como una cadena en lugar de un objeto. Valida y normaliza los argumentos antes de la invocación y conserva el mensaje de error útil del servidor para la depuración.

Otro error común es exponer las herramientas de todos los servidores conectados a todos los usuarios. Los nombres y las descripciones de las herramientas pueden solaparse, y un servidor malicioso o configurado incorrectamente puede presentar una capacidad insegura. Utiliza una lista explícita de servidores permitidos, aísla las credenciales, aplica autorización por herramienta, establece tiempos de espera, limita las llamadas repetidas y registra qué usuario, decisión del modelo, servidor y herramienta estuvieron involucrados. Estos controles hacen que el comportamiento del agente sea observable y más fácil de revisar.

Resumen

Un agente habilitado para MCP se entiende mejor como una aplicación host con dos componentes que cooperan. El modelo razona sobre la intención del usuario y propone una llamada estructurada, mientras que el cliente MCP descubre las capacidades y ejecuta la operación conforme al protocolo. El cliente nunca debe asumir que una herramienta existe simplemente porque el modelo la ha mencionado; debe descubrir las herramientas actuales, validar la selección y los argumentos, y aplicar la política local antes de invocarla.

El flujo de trabajo práctico consiste en inicializar, listar las herramientas, presentar sus esquemas al modelo, validar la llamada propuesta por el modelo, invocar la herramienta seleccionada y devolver el resultado para el razonamiento final. Una vez que este ciclo funciona con un servidor, puede ampliarse a varios servidores y tareas de varios pasos sin cambiar el límite central. Las decisiones de implementación más importantes siguen siendo la configuración explícita del transporte, la validación estricta, la autorización segura, la ejecución acotada y la generación de informes de errores útiles.