LLMs y herramientas externas. En lugar de construir integraciones ad-hoc para cada agente,
MCP define una interfaz \u00fanica: el agente descubre tools, las invoca con JSON-RPC 2.0, y el
servidor ejecuta la l\u00f3gica.<\/p>\n\n\n\n
En este art\u00edculo explico c\u00f3mo construimos un MCP server que integra cuatro servicios
complementarios para proporcionar a cualquier LLM (Claude, GPT, Gemini, etc.) capacidades de b\u00fasqueda, navegaci\u00f3n web interactiva, extracci\u00f3n de contenido y OCR mediante una \u00fanica interfaz MCP:<\/p>\n\n\n\n
- \n
- SearXNG<\/strong>: metab\u00fasqueda privada y autogestionada<\/li>\n\n\n\n
- Firecrawl<\/strong>: scraping, crawling y extracci\u00f3n estructurada<\/li>\n\n\n\n
- Camofox<\/strong>: navegaci\u00f3n headless con anti-detecci\u00f3n<\/li>\n\n\n\n
- OCR iOS<\/strong>: reconocimiento de texto local v\u00eda Apple Vision Framework<\/li>\n<\/ul>\n\n\n\n
Arquitectura general<\/h2>\n\n\n\n
El servidor MCP act\u00faa como un proxy unificado<\/strong> entre el LLM y los servicios. No expone
los servicios directamente, sino que ofrece tools que el LLM invoca seg\u00fan necesidad.<\/p>\n\n\n\n![\"\"](\"https:\/\/atlaszn.com\/blog\/wp-content\/uploads\/2026\/07\/diagrama_mcp-1024x683.webp\")
<\/figure>\n\n\n\nCada tool del MCP server llama a su servicio v\u00eda HTTP. El LLM nunca ve los servicios
directamente, solo ve las tools con sus nombres, descripciones y par\u00e1metros.<\/p>\n\n\n\nDecisiones de dise\u00f1o <\/h2>\n\n\n\n
1. FastMCP vs MCP SDK raw<\/h3>\n\n\n\n
Usamos
FastMCP<\/code> del SDK oficial (mcp.server.fastmcp<\/code>). FastMCP es una capa sobre el
protocolo MCP que elimina boilerplate: genera autom\u00e1ticamente el JSON Schema de cada tool
a partir de type hints y docstrings, maneja el lifecycle del protocolo, y soporta m\u00faltiples
transportes sin configuraci\u00f3n adicional.<\/p>\n\n\n\nFastMCP abstrae el protocolo, lo que es bueno para productividad pero limita
el control fino sobre mensajes JSON-RPC individuales. Para nuestro caso (tools simples sin
streaming) parece una decisi\u00f3n correcta.<\/p>\n\n\n\n2. Transporte: stdio vs Streamable HTTP<\/h3>\n\n\n\n
Soportamos ambos.
stdio<\/code> es ideal cuando el cliente MCP (Claude Desktop, Cursor) lanza el
server como subproceso local.streamable-http<\/code> es necesario cuando el server corre en
una m\u00e1quina remota.<\/p>\n\n\nTradeoff importante:<\/strong>\u00a0stdio\u00a0es m\u00e1s simple y seguro (no requiere puertos abiertos), pero
ata el ciclo de vida del server al del cliente. HTTP permite servir a m\u00faltiples clientes,
pero requiere configuraci\u00f3n de red, firewalls y posiblemente autenticaci\u00f3n.<\/div><\/div>\n\n\nEn una topolog\u00eda con el LLM en
10.0.1.5<\/code>, los servicios en10.0.1.8<\/code> y el MCP server en otra m\u00e1quina, ambas opciones son viables. La elecci\u00f3n depende principalmente de la infraestructura disponible y de si el servidor ser\u00e1 utilizado por uno o varios clientes.<\/p>\n\n\n\n- \n
- Opci\u00f3n A (SSH):<\/strong> el cliente en
10.0.1.5<\/code> lanzassh user@mcp-server python server.py<\/code>
como comando stdio. No requiere abrir puertos.<\/li>\n\n\n\n- Opci\u00f3n B (HTTP):<\/strong> el server corre con
--transport streamable-http --port 8001<\/code> y el cliente se conecta ahttp:\/\/mcp-server:8001\/mcp<\/code>. Requiere el puerto accesible.<\/li>\n<\/ul>\n\n\n\n3. Cliente HTTP global vs por request<\/h3>\n\n\n\n
Una de las primeras correcciones que hicimos fue centralizar el cliente HTTP:<\/p>\n\n\n\n
http_client = httpx.AsyncClient(\n timeout=httpx.Timeout(connect=10.0, read=30.0, write=30.0, pool=30.0),\n limits=httpx.Limits(max_keepalive_connections=20, max_connections=100),\n)<\/code><\/pre>\n\n\n\nAntes<\/strong> cada request creaba su propio
AsyncClient<\/code>, lo que implicaba:<\/p>\n\n\n\n- \n
- Negociaci\u00f3n TCP en cada llamada (handshake + TLS)<\/li>\n\n\n\n
- Sin reuso de conexiones<\/li>\n\n\n\n
- Mayor latencia y carga en los servicios<\/li>\n<\/ul>\n\n\n\n
Despu\u00e9s<\/strong> con un cliente global con pool de conexiones keep-alive:<\/p>\n\n\n\n
- \n
- Las conexiones se reusan entre requests<\/li>\n\n\n\n
- El l\u00edmite
max_connections=100<\/code> permite controlar el n\u00famero m\u00e1ximo de conexiones simult\u00e1neas abiertas por el cliente HTTP. El valor adecuado depender\u00e1 de la capacidad de los servicios de destino y de la carga esperada.<\/li>\n\n\n\n- Se define un timeout granular por operaci\u00f3n (connect, read, write, pool)<\/li>\n<\/ul>\n\n\n\n
El cliente global complica el shutdown (hay que cerrarlo expl\u00edcitamente al
salir). Lo resolvemos con untry\/finally<\/code> en el bloque__main__<\/code>.<\/p>\n\n\n\n4. SSRF protecci\u00f3n resolviendo DNS<\/h3>\n\n\n\n
Aceptar URLs arbitrarias del LLM implica riesgo de Server-Side Request Forgery (SSRF).
Un LLM malicioso o comprometido podr\u00eda intentar acceder ahttp:\/\/169.254.169.254\/latest\/meta-data\/<\/code>
(metadata cloud) o a servicios internos.<\/p>\n\n\n\nNuestra validaci\u00f3n:<\/p>\n\n\n\n
- \n
- Verifica esquema HTTP\/HTTPS solamente<\/li>\n\n\n\n
- Resuelve el hostname a IP con
socket.gethostbyname()<\/code><\/li>\n\n\n\n- Bloquea IPs privadas, loopback y link-local con
ipaddress<\/code> module<\/li>\n<\/ol>\n\n\n\ndef _es_ip_privada(host):\n ip = ipaddress.ip_address(host)\n return ip.is_private or ip.is_loopback or ip.is_link_local\n \ndef _resolver_y_validar(host):\n ip = socket.gethostbyname(host)\n if _es_ip_privada(ip):\n raise ValueError(f\"Host {host} resuelve a IP privada {ip}\")<\/code><\/pre>\n\n\n\nTradeoff:<\/strong> Resolver DNS en cada llamada a\u00f1ade una peque\u00f1a latencia adicional, cuyo impacto depender\u00e1 de la cach\u00e9 DNS del sistema operativo, la red y el resolvedor utilizado. Validar \u00fanicamente el formato del hostname no es suficiente frente a determinados escenarios como DNS rebinding. Resolver el nombre antes de comprobar la IP reduce significativamente la superficie de ataque frente a una validaci\u00f3n basada \u00fanicamente en el hostname, aunque no elimina todos los escenarios de SSRF (por ejemplo DNS rebinding o cambios de resoluci\u00f3n posteriores a la validaci\u00f3n).<\/p>\n\n\n\n
5. M\u00faltiples servicios unificados vs separados<\/h3>\n\n\n\n
Podr\u00edamos haber creado 4 servidores MCP independientes (uno por servicio). En su lugar
los unificamos en un solo server con tools nombradas por prefijosearxng_*<\/code>,firecrawl_*<\/code>,camofox_*<\/code>,ocr_*<\/code>).<\/p>\n\n\n\nVentajas de unificarlos:<\/strong><\/p>\n\n\n\n
- \n
- Una sola configuraci\u00f3n para el usuario<\/li>\n\n\n\n
- Un solo proceso que gestionar<\/li>\n\n\n\n
- El LLM ve todas las tools disponibles sin cambiar de \u00abcontexto\u00bb<\/li>\n\n\n\n
- Las tools pueden combinarse en un mismo flujo de razonamiento<\/li>\n<\/ul>\n\n\n\n
Desventajas:<\/strong><\/p>\n\n\n\n
- \n
- Si un servicio falla (ej. Camofox ca\u00eddo), todas las tools aparecen como disponibles
pero pueden fallar<\/li>\n\n\n\n - Mayor acoplamiento: actualizar la l\u00f3gica de un servicio requiere tocar el mismo archivo<\/li>\n\n\n\n
- Un solo punto de fallo<\/li>\n<\/ul>\n\n\n\n
En despliegues donde distintos equipos gestionan cada servicio o donde se requiere aislamiento entre componentes, separar los servidores puede simplificar la operaci\u00f3n. En otros escenarios, especialmente para uso personal o equipos peque\u00f1os, un \u00fanico MCP resulta m\u00e1s sencillo de administrar.<\/p>\n\n\n\n
6. Retries autom\u00e1ticos<\/h3>\n\n\n\n
Inicialmente configuramos
httpx.AsyncHTTPTransport(retries=2)<\/code> a nivel de transporte.
Lo eliminamos al descubrir que retry autom\u00e1tico en POST requests puede causar efectos
secundarios graves: doble crawl, doble extracci\u00f3n, doble navegaci\u00f3n.<\/p>\n\n\n\nDecisi\u00f3n final:<\/strong> sin retries autom\u00e1ticos. Cada tool maneja sus errores espec\u00edficos
(timeout, HTTP error, conexi\u00f3n) con mensajes claros para el LLM, que puede decidir
reintentar o no. Esto no significa que los retries sean siempre una mala idea. En operaciones idempotentes (por ejemplo, muchas peticiones GET) pueden mejorar la resiliencia del sistema. En nuestro caso preferimos deshabilitarlos globalmente para evitar efectos secundarios en operaciones que modifican estado.<\/p>\n\n\n\n7. OCR: URL vs Base64<\/h3>\n\n\n\n
El servidor OCR expone un endpoint HTTP sencillo (
POST \/upload<\/code>) que recibe im\u00e1genes mediante una petici\u00f3n multipart.<\/p>\n\n\n\n- \n
ocr_imagen_url<\/code>: descarga la imagen desde una URL y la reenv\u00eda al OCR<\/li>\n\n\n\nocr_imagen_base64<\/code>: recibe la imagen como base64 directamente<\/li>\n<\/ul>\n\n\n\nURL es m\u00e1s eficiente (no pasa datos binarios por MCP), pero requiere que
la imagen sea accesible p\u00fablicamente. Base64 funciona para cualquier imagen (capturas
locales, fotos reci\u00e9n tomadas, im\u00e1genes generadas por el LLM), pero puede saturar
el contexto si la imagen es grande. Nuestro l\u00edmite pr\u00e1ctico ser\u00e1n ~20MB.<\/p>\n\n\n\n8. Observabilidad<\/h3>\n\n\n\n
Cada herramienta envuelve sus llamadas HTTP con:<\/p>\n\n\n\n
- \n
- Request ID<\/strong> (UUID hex de 8 chars) para correlacionar logs<\/li>\n\n\n\n
- Timing<\/strong> con
time.monotonic()<\/code> para medir latencia<\/li>\n\n\n\n- Logging estructurado<\/strong> con niveles (info para \u00e9xito, error para fallos)<\/li>\n<\/ul>\n\n\n\n
log.info(\"[%s] GET %s \u2192 %s (%dms)\", rid, url, resp.status_code, int(elapsed * 1000))<\/code><\/pre>\n\n\n\nEl logging detallado agrega overhead de I\/O. En nuestro escenario de uso, donde predominan pocas peticiones relativamente costosas (navegaci\u00f3n, OCR o scraping), el coste adicional del logging resulta peque\u00f1o frente al tiempo total de ejecuci\u00f3n. En sistemas de mayor volumen podr\u00edan ser preferibles estrategias como logging as\u00edncrono, muestreo o agregaci\u00f3n de eventos.<\/p>\n\n\n\n
9. Truncado de respuestas<\/h3>\n\n\n\n
Aunque el protocolo MCP no impone un l\u00edmite estricto para las respuestas de las herramientas, en la pr\u00e1ctica el tama\u00f1o \u00fatil est\u00e1 condicionado por el cliente MCP, el modelo utilizado y la ventana de contexto disponible. Por ello implementamos dos estrategias de truncado:<\/p>\n\n\n\n
- \n
- Por caracteres<\/strong> (
truncar_por_caracteres<\/code>): corta a 8000 chars. Ideal para texto
plano (OCR, contenido de p\u00e1ginas).<\/li>\n\n\n\n- Por l\u00edneas<\/strong> (
truncar_por_lineas<\/code>): corta a 80 l\u00edneas. Ideal para listas de
resultados (b\u00fasquedas, mapas de sitio).<\/li>\n<\/ul>\n\n\n\nEl truncado incluye un mensaje \u00ab[Truncado \u2014 respuesta demasiado larga]\u00bb para que el LLM
sepa que la respuesta est\u00e1 incompleta y pueda pedir m\u00e1s si es necesario.<\/p>\n\n\n\n10. Excepciones espec\u00edficas vs gen\u00e9ricas<\/h3>\n\n\n\n
Evolucionamos de
except Exception as e<\/code> (que oculta bugs de l\u00f3gica y filtra informaci\u00f3n
interna al usuario) a manejo granular:<\/p>\n\n\n\nexcept httpx.TimeoutException:\n return \"Error: el servicio no respondi\u00f3 a tiempo\"\nexcept httpx.HTTPStatusError as e:\n log.error(\"HTTP %s: %s\", e.response.status_code, e.response.text[:300])\n return \"Error: el servicio respondi\u00f3 con un c\u00f3digo de error\"\nexcept httpx.HTTPError as e:\n log.error(\"Error de conexi\u00f3n: %s\", e)\n return \"Error: no se pudo conectar con el servicio\"<\/code><\/pre>\n\n\n\nPrincipio:<\/strong> el usuario ve mensajes gen\u00e9ricos y accionables; los detalles t\u00e9cnicos
(IPs, stack traces, cuerpos de respuesta) van solo a los logs.<\/p>\n\n\n\n
\n\n\n\nLecciones aprendidas<\/h2>\n\n\n\n
- \n
- Nombrar el archivo
mcp.py<\/code> shadowea el paquete.<\/strong> Suena obvio, pero es el error
m\u00e1s com\u00fan al empezar con MCP en Python. El archivo debe llamarse cualquier otra cosa.<\/li>\n\n\n\n- FastMCP tiene dos implementaciones habituales:<\/strong> la del SDK oficial (
mcp.server.fastmcp<\/code>) y la
standalonefastmcp<\/code> de Prefect). Tienen APIs distintas. La oficial no tieneon_shutdown<\/code>, la de Prefect s\u00ed.<\/li>\n\n\n\n- El LLM no entiende de infraestructura.<\/strong> El modelo no dispone de conocimiento espec\u00edfico sobre la infraestructura de despliegue. Por ello las herramientas deben describirse en t\u00e9rminos funcionales (\u00abbuscar\u00bb, \u00abextraer\u00bb, \u00abnavegar\u00bb) y no mediante detalles internos de implementaci\u00f3n.<\/li>\n\n\n\n
- El contexto MCP es limitado.<\/strong> Las respuestas de tools deben ser concisas.
Un resultado de OCR con 5000 caracteres de texto es m\u00e1s \u00fatil que uno con 50000
que nunca llega al LLM porque excede el l\u00edmite del protocolo.<\/li>\n\n\n\n- Protecci\u00f3n SSRF.<\/strong> Si un MCP server acepta URLs proporcionadas por el LLM, conviene incorporar protecci\u00f3n frente a SSRF desde el principio. Resolver el hostname antes de validar la IP evita una clase importante de ataques y representa una mejora significativa frente a validar \u00fanicamente el formato de la URL, aunque no sustituye otras medidas de defensa que puedan ser necesarias en entornos especialmente sensibles.<\/li>\n<\/ol>\n\n\n\n
\n\n\n\nConclusi\u00f3n<\/h2>\n\n\n\n
Construir un MCP server que integra b\u00fasqueda, navegaci\u00f3n web mediante un navegador real, extracci\u00f3n de contenido y OCR combina infraestructura, protocolos y dise\u00f1o de herramientas orientadas a agentes. La clave est\u00e1 en las decisiones de borde: c\u00f3mo truncar, c\u00f3mo autenticar, c\u00f3mo validar, cu\u00e1ndo retry, qu\u00e9 loggear.<\/p>\n\n\n\n
- FastMCP tiene dos implementaciones habituales:<\/strong> la del SDK oficial (
- Por l\u00edneas<\/strong> (
- Timing<\/strong> con
- Si un servicio falla (ej. Camofox ca\u00eddo), todas las tools aparecen como disponibles
- Bloquea IPs privadas, loopback y link-local con
- Se define un timeout granular por operaci\u00f3n (connect, read, write, pool)<\/li>\n<\/ul>\n\n\n\n
- Opci\u00f3n B (HTTP):<\/strong> el server corre con
- Firecrawl<\/strong>: scraping, crawling y extracci\u00f3n estructurada<\/li>\n\n\n\n