En el contexto de la creación de herramientas con MCP, no hay un modelo único para estructurar el código, pero es recomendable seguir buenas prácticas de programación. Puedes encontrar ejemplos y referencias en la documentación de SERP API y otros recursos de desarrollo disponibles en línea. Además, revisa proyectos similares en GitHub para obtener ideas sobre la estructura y organización del código. Esto facilitará la implementación eficiente y clara de tus herramientas.
Recursos
Resumen
Crear un MCP de búsqueda web con SERP API es el paso donde todo lo visto sobre servidores MCP se vuelve un producto real y funcional. Si estás aprendiendo a construir sistemas de AI con capacidades de búsqueda en internet, aquí verás cómo configurar la cuenta, proteger tu llave de API y armar tu primera herramienta de búsqueda general.
Por qué necesitas SERP API para buscar en la web
Un MCP por sí solo no puede consultar Google. Necesita un servicio externo que haga esa conexión, y ahí entra SERP API, un servicio gratuito que te permite ejecutar búsquedas web desde tu código.
Lo mejor es que crear la cuenta es lo que más tiempo te toma. Puedes registrarte con tu cuenta de GitHub, con Gmail más un teléfono, o con un correo electrónico, y obtienes acceso al plan gratuito sin pagar nada.
¿Qué es SERP API? Es un servicio que te permite hacer búsquedas en motores como Google desde tu código y recibir los resultados en formato estructurado. Tiene una capa gratuita que activas con GitHub, Gmail o correo.
Una vez dentro, vas a la sección de API key y copias la llave que aparece ahí. Esa llave es la que tu servidor usará para autenticarse. Y aquí viene un detalle importante sobre seguridad: aunque la llave se vea en pantalla, basta con presionar un botón para regenerarla, así que exponerla en un curso no representa riesgo real.
Cómo proteger tu API key con archivos .env
La llave nunca va directa en el código. Para eso usamos un archivo .env, que guarda tus variables sensibles fuera del código visible.
Dentro de la clase 18, creamos primero el archivo .env con la variable SERP_API_KEY y su valor entre comillas. Esto mantiene la llave separada y segura.
Además, se agrega un segundo archivo llamado .env-sample, que sirve como referencia para quien revise el repositorio. Este archivo muestra la estructura esperada pero con un texto genérico como "tu API key", para que cualquiera sepa qué variable necesita sin exponer la llave real [03:00].
¿Para qué sirve un archivo .env-sample? Es una plantilla que muestra qué variables de entorno necesita el proyecto, pero sin valores reales. Permite que otros repliquen tu configuración sin compartir datos sensibles.
Qué elementos importar para armar el servidor
El archivo server.py arranca importando varios elementos que trabajan en conjunto. Cada uno cumple una función concreta dentro del flujo de búsqueda.
os, para acceder a las variables del archivo.env.jsonyhttpx, para trabajar con el formato de datos y hacer las consultas web.load_dotenv, el método que carga el archivo de entorno.FastMCP, el servidor MCP que ya veníamos usando.logging, para registrar qué funciona y qué falla.
Después de importar, se usa load_dotenv para cargar la configuración y se extrae la SERP_API_KEY. Si la llave no existe, el código lanza un error de inmediato, avisándote que algo está mal configurado antes de que el problema crezca [04:40].
Por qué el logging es clave en sistemas de AI
Aquí hay una obsesión que vale la pena adoptar: ponerle logs a todos tus proyectos. La observabilidad es una de las partes más importantes de los sistemas de AI porque te permite saber qué está fallando y qué está funcionando.
Gracias a ese registro detallado puedes mejorar tus sistemas de forma mucho más rápida. No es un detalle opcional, es la diferencia entre adivinar y saber.
También se definen tres valores de configuración base: la URL base del servicio (que es fija e inamovible), el timeout o tiempo de espera, y el máximo de resultados posibles. Como trabajamos con la capa gratuita, el máximo de resultados se deja en cinco para no forzar el límite [05:50].
Cómo construir la primera herramienta de búsqueda
Con la configuración lista, llega el servidor FastMCP Web Search Server y el método que hace la magia: make_serp_api_request, encargado de armar y enviar la solicitud a la API.
Hay un detalle sobre idioma que conviene imitar. Cuando el MCP es académico o de aprendizaje, la documentación va en español. Cuando es un proyecto real y en forma, casi todo se escribe en inglés, porque no sabes quién lo va a usar. Lo ideal es acostumbrarte a documentar en ambos idiomas.
La solicitud contempla varios escenarios de error, y esto le sonará familiar a cualquiera que desarrolle APIs:
- Un
timeoutcuando la consulta tarda demasiado. - Un error de HTTP en la respuesta.
- Un manejo de JSON cuando los datos llegan mal formados.
Como suele pasar en el desarrollo de APIs, hay un solo escenario donde todo sale bien y cerca de 25,000 escenarios donde algo puede salir mal. Por eso el manejo de errores pesa tanto.
Qué parámetros necesita la herramienta General Search
La primera herramienta se llama general_search y ejecuta una búsqueda web general, como si buscaras algo directamente en Google. Recibe parámetros específicos para funcionar.
- La consulta de búsqueda, es decir, lo que quieres buscar.
- El número de resultados, que viene por default en cinco.
- El root context del MCP, que ya habíamos usado antes.
Ese contexto es clave porque permite acumular la información y mantenerla presente en búsquedas sucesivas. Si no hay resultados, la herramienta avisa que no están disponibles; si los hay, los despliega de forma más eficiente [09:00].
¿Qué hace el root context en un MCP? Es el contexto que permite al servidor acumular información de búsquedas anteriores y tenerla presente en consultas posteriores, dando continuidad a la sesión.
Para probar todo, se abre la terminal, se navega a la carpeta de la clase 18 y se lanza el inspector con el comando mcp dev run server.py. Tras conectar, las herramientas aparecen listadas y ahí está general_search, funcionando [10:30].
Esta es apenas la primera de muchas herramientas. En el siguiente paso se agregan más métodos para convertir el servidor en algo verdaderamente versátil. ¿Qué otra herramienta de búsqueda te gustaría agregarle? Cuéntame en los comentarios.
