MCP Hello Page es una técnica simple y efectiva para mejorar la experiencia de onboarding de servidores MCP: cuando alguien abre la URL del servidor en un navegador en vez de en un cliente MCP, en lugar de recibir un error 401 con un JSON crudo, recibe una página HTML que le explica qué está mirando y cómo usarlo correctamente.
En 30 segundos
- Los servidores MCP devuelven error 401 + JSON cuando alguien los abre en el navegador, generando tickets de soporte innecesarios.
- La solución es detectar el header
Accept: text/htmly devolver una página HTML amigable en vez de la respuesta técnica. - HybridLogic implementó esto en 2026 y vio caer sus tickets de soporte “off a cliff” (literalmente, como barranco).
- No requiere crear conectores para cada cliente MCP, que es la alternativa obvia pero mucho más costosa de mantener.
- La implementación es de pocas líneas de código en cualquier lenguaje.
Qué es MCP Hello Page
MCP Hello Page es una página HTML de bienvenida que un servidor MCP sirve cuando detecta que la solicitud viene de un navegador web, en vez de la respuesta JSON estándar que esperaría un cliente MCP. La idea es puramente de UX: el servidor distingue si quien pide es un humano navegando o una herramienta automatizada, y responde en consecuencia.
El protocolo MCP (Model Context Protocol) es el estándar abierto que publicó Anthropic para que las herramientas de IA puedan conectarse a fuentes de datos y servicios externos. Un servidor MCP expone capacidades que los clientes de LLMs pueden consumir. El problema: esos servidores tienen URLs, y las URLs las abren las personas en navegadores.
El problema: Error 401 y confusión del usuario
Ponele que le das a un cliente la URL de tu servidor MCP: mcp.tuempresa.com/mcp. Lo que hace el 80% de las personas es abrir eso en Chrome o Firefox. Lo que ven es un 401 Unauthorized con un blob de JSON crudo que dice algo así como {"error": "Unauthorized"}.
Resultado inmediato: ticket de soporte. “El link no funciona.” “La integración está caída.” “No puedo conectarme.” Para más detalles técnicos, mirá optimizar contenido para AI Overviews.
Según Luke Lanchester de HybridLogic, esto fue exactamente lo que vivieron cuando lanzaron su servidor MCP para su herramienta principal. Los usuarios abrían la URL, veían el error, y en vez de pensar “tengo que pegarlo en el cliente”, pensaban “esto está roto”. Lo cual tiene toda la lógica del mundo: si una URL da error, el instinto es reportarlo.
El problema no es técnico. El servidor MCP funciona perfectamente. El problema es que el servidor responde como lo que es: una API pensada para clientes que hablan el protocolo, no para personas que miran pantallas.
Cómo funciona la detección del header Accept
La solución que implementó HybridLogic es lo que el mismo Lanchester llama “a little bit hacky”: chequeás el header Accept de la request. Si incluye text/html, significa que quien pide es un navegador. Si no lo incluye (o incluye application/json), es un cliente MCP o una herramienta.
Con eso sabés exactamente qué devolver.
¿Y qué tan confiable es esa detección? Para el caso de uso específico (navegador vs. cliente MCP), suficientemente confiable. Los navegadores siempre incluyen text/html en Accept. Los clientes MCP bien implementados no lo hacen. No es una heurística perfecta, pero en la práctica cubre el 99% de los casos reales.
Implementación paso a paso
La lógica central es la misma en cualquier lenguaje. Acá va el patrón básico en Python y en TypeScript para que lo adaptés a tu stack.
Python (FastAPI o similar)
Si tu servidor MCP está en Python con FastAPI o cualquier framework que te dé acceso a los headers: Más contexto en herramientas para escalar con Claude.
from fastapi import Request
from fastapi.responses import HTMLResponse, JSONResponse
@app.get("/mcp")
async def mcp_endpoint(request: Request):
accept = request.headers.get("accept", "")
if "text/html" in accept:
return HTMLResponse(content=get_hello_page(), status_code=200)
# Lógica normal del servidor MCP
return handle_mcp_request(request)
def get_hello_page():
return """
Servidor MCP - Mi Empresa
Este es un servidor MCP
Esta URL no se abre en el navegador. Tenés que agregarla a tu cliente MCP.
Cómo agregarlo
- Claude Desktop: Abrí la configuración y pegá esta URL en la sección MCP Servers.
- Cursor: En Settings > MCP, agregá un nuevo servidor con esta URL.
URL del servidor: https://mcp.tuempresa.com/mcp
"""
TypeScript / Node.js
Para un servidor Express o similar:
import { Request, Response } from 'express';
app.get('/mcp', (req: Request, res: Response) => {
const accept = req.headers['accept'] ?? '';
if (accept.includes('text/html')) {
return res.status(200).send(getHelloPage());
}
// Manejo normal del protocolo MCP
return handleMcpRequest(req, res);
});
function getHelloPage(): string {
return `
Servidor MCP
Servidor MCP de Mi Empresa
Abriste la URL del servidor MCP en un navegador.
Esta URL tiene que ir en tu cliente MCP, no en Chrome.
Copiá esta URL y pegala en tu herramienta de IA:
https://mcp.tuempresa.com/mcp
`;
}
La página en sí debería tener: una explicación de qué es MCP (sin tecnicismos), instrucciones concretas para los clientes más comunes, y la URL del servidor bien visible para copiar y pegar. Nada más. Cuanto más simple, mejor.
Resultados: los tickets se fueron al piso
HybridLogic reportó que el número de tickets de soporte cayó radicalmente después de implementar la Hello Page. El equipo de Customer Success lo notó de inmediato, y los usuarios ahora se configuran solos con mayor frecuencia. No hay cifras exactas publicadas, pero Lanchester lo describe como que el volumen “dropped off a cliff”, que es bastante elocuente.
Lo interesante es que la solución no requirió ningún cambio en el protocolo, ninguna integración con clientes externos, ni documentación nueva que nadie lee de todas formas. Solo una condicional en el endpoint y una página HTML estática.
Para equipos que manejan un volumen considerable de clientes onboardeando servidores MCP, esto es la diferencia entre soporte escalable y una cadena infinita de tickets que dicen “el link no funciona”. Tema relacionado: capacidades de procesamiento de imágenes.
Por qué no basta con crear conectores para cada cliente
La alternativa obvia es empaquetar el servidor MCP como un plugin o conector para cada plataforma: Claude Desktop, Cursor, Windsurf, Continue, y cualquier otro cliente que exista.
El problema lo explica bien Lanchester: es un juego infinito de whack-a-mole. Cada mes aparece un cliente nuevo. Las empresas construyen sus propios clientes internos embebidos. Mantener un conector para cada uno es lento, consume tiempo de ingeniería y nunca termina. Y mientras tanto, el usuario que tiene el cliente genérico nuevo que no tiene conector sigue viendo el 401.
La Hello Page cubre todos esos casos de una vez. No importa si el usuario está usando un cliente que vos no conocías que existía: si lo abre en un navegador, ve la página. Si lo usa desde el cliente correcto, el servidor responde normalmente.
Mejores prácticas para tu Hello Page
Si vas a implementar esto, hay algunas cosas que marcan la diferencia entre una página que ayuda y una que confunde un poco menos:
- Explicá qué es MCP en una oración: “MCP es el protocolo que permite a las herramientas de IA conectarse a servicios externos.” Nada más. No asumas que el usuario sabe qué es.
- Mostrá instrucciones por cliente: Claude Desktop, Cursor, Windsurf, Continue. Con los pasos exactos, no genéricos. Si podés agregar capturas, mejor.
- Ponés la URL grande y con botón de copiar: es lo único que el usuario necesita. Hacéla visible.
- No pongas documentación extensa: si necesitás 10 pasos para explicar cómo agregar el servidor, el problema es otro. La página tiene que ser rápida de escanear.
- Cargá rápido: nada de dependencias externas. HTML puro o con CSS inline. El usuario ya está confundido, no le sumés un spinner.
Tabla comparativa: Hello Page vs. Conectores por cliente
| Criterio | MCP Hello Page | Conector por cliente |
|---|---|---|
| Tiempo de implementación | Horas | Días por cliente |
| Mantenimiento | Casi nulo | Continuo por cada versión |
| Cobertura de clientes | Cualquier cliente/navegador | Solo los clientes soportados |
| Clientes internos de empresas | Sí | No (habría que crear uno por empresa) |
| Clientes nuevos sin soporte | Sí (automático) | No |
| Reduce tickets de soporte | Sí (drásticamente) | Parcialmente |
| Requiere cambios en el protocolo | No | No |
Lo que está confirmado y lo que no
Confirmado
- HybridLogic implementó MCP Hello Page en mayo de 2026 y reportó reducción notable de tickets de soporte.
- La técnica usa el header
Accept: text/htmlpara detectar requests de navegadores. - El approach cubre clientes MCP personalizados que los conectores standard no podrían cubrir.
- La implementación no requiere modificar el protocolo MCP ni depender de herramientas externas.
Pendiente / sin confirmar
- No hay cifras exactas publicadas sobre la reducción porcentual de tickets.
- No se sabe si Anthropic o la comunidad MCP adoptará esto como una recomendación oficial en la documentación del protocolo.
- Algunos clientes MCP no estándar podrían enviar
Accept: text/htmlsin ser navegadores (edge case poco probable pero posible).
Errores comunes al implementar MCP Hello Page
Devolver 200 con HTML cuando debería ser otra cosa
Si tu servidor requiere autenticación y el usuario no está autenticado, la Hello Page igual puede devolver 200 con contenido HTML (para browsers). El error 401 original era técnicamente correcto, pero inútil para un humano. La Hello Page no necesita respetar el status code original: su trabajo es comunicar, no ser técnicamente rigurosa con el HTTP. Te puede servir nuestra cobertura de integrar APIs de IA con Node.js.
Poner instrucciones genéricas sin mencionar los clientes reales
Una página que dice “agregá esta URL a tu cliente MCP favorito” es casi tan inútil como el 401. Si el usuario no sabe qué es MCP, tampoco sabe qué cliente usar. Listá los clientes más comunes con pasos concretos: Claude Desktop, Cursor, Continue. Eso es lo que hace que la página funcione.
Aplicar la detección solo en el endpoint raíz y no en sub-rutas
Si tu servidor tiene la ruta /mcp como entry point pero también /mcp/health o /mcp/info, los usuarios pueden llegar a cualquiera de esas URLs desde un link en la documentación. La detección de Accept header debería estar en un middleware global del servidor, no solo en el endpoint principal.
Preguntas Frecuentes
¿Qué es MCP Hello Page?
MCP Hello Page es una página HTML que un servidor MCP devuelve cuando detecta que la solicitud viene de un navegador web en vez de un cliente MCP. Sirve para orientar al usuario en vez de mostrarle un error técnico crudo. La detección se hace revisando si el header Accept de la request incluye text/html.
¿Por qué mi servidor MCP muestra error 401 en el navegador?
Porque el servidor MCP está diseñado para responder a clientes que hablan el protocolo MCP, no a navegadores. El 401 es correcto técnicamente si el servidor requiere autenticación, pero es inútil para un usuario que no entiende qué está mirando. La solución es implementar una Hello Page que detecte el navegador y responda con HTML explicativo.
¿Cómo implementar una página de bienvenida en un servidor MCP?
Revisás el header Accept en cada request: si incluye text/html, devolvés una página HTML con instrucciones para agregar el servidor al cliente MCP. Si no, procesás la request normalmente. Son menos de 20 líneas de código en cualquier framework web moderno.
¿Cómo reducir tickets de soporte con MCP Hello Page?
Implementando la Hello Page con instrucciones claras por cliente (Claude Desktop, Cursor, etc.) y la URL del servidor bien visible. HybridLogic reportó en mayo de 2026 que sus tickets de soporte relacionados al onboarding del servidor MCP cayeron drásticamente tras implementar esta solución. El usuario que antes reportaba “el link no funciona” ahora puede autoconfigurarse.
¿Cómo detectar si acceden desde navegador o cliente MCP?
Revisás el header HTTP Accept de la request entrante. Los navegadores siempre incluyen text/html en ese header. Los clientes MCP bien implementados envían application/json o no incluyen text/html. Con esa diferencia ya tenés suficiente para distinguir los dos casos en la práctica.
Conclusión
MCP Hello Page es una solución que resuelve un problema real con elegancia mínima: unas pocas líneas de código que chequean un header y sirven HTML en vez de JSON. No hay nada nuevo acá, pero tampoco hacía falta nada nuevo.
Lo que HybridLogic documentó en mayo de 2026 es algo que cualquier equipo que esté exponiendo un servidor MCP va a enfrentar tarde o temprano. Los usuarios abren URLs en navegadores, ven errores, reportan tickets. Con una Hello Page bien pensada, ese ciclo se corta. Si tenés un servidor MCP expuesto o estás por lanzar uno, implementar esto antes de salir a producción vale mucho más que horas de soporte después.
Si además tu infraestructura MCP corre en servidores propios o en hosting en Argentina, fijate que el proveedor soporte las configuraciones de headers necesarias sin restricciones. Para eso donweb.com tiene opciones de VPS y cloud donde tenés control total sobre tu stack.