Cómo descubren los clientes las herramientas y los recursos
El descubrimiento se produce en dos etapas: averiguar cómo autenticarse y, después, averiguar qué hay disponible. Un cliente compatible hace ambas cosas sin más configuración que la URL del servidor.
Etapa uno: cómo autenticarse
- El cliente llama al endpoint MCP sin credenciales.
- El servidor responde
401con una cabeceraWWW-Authenticateque indica la URL de los metadatos del recurso protegido. - El cliente lee ese documento, que identifica el recurso y señala este sitio como su servidor de autorización.
- El cliente lee los metadatos del servidor de autorización, que enumeran los endpoints de registro, autorización y token, los flujos de concesión admitidos y los ámbitos disponibles.
- El cliente se registra y completa el flujo OAuth.
Por eso solo tienes que darle a un cliente la URL del MCP. Todo lo demás se anuncia.
Consulta Metadatos del recurso protegido y Metadatos del servidor de autorización.
La cabecera WWW-Authenticate solo se envía cuando OAuth está activado. Con OAuth desactivado, una petición no autenticada sigue devolviendo 401 pero sin el puntero, de modo que un cliente no puede iniciar el arranque — algo esperable, ya que el modo de clave de API requiere configuración manual.
Etapa dos: qué hay disponible
Una vez autenticado, el cliente llama a initialize y recibe la versión del protocolo negociada, el nombre del servidor procedente de tu ajuste Server label, y las capacidades que anuncia el servidor: herramientas, recursos y prompts.
Después los enumera:
| Llamada | Devuelve |
|---|---|
tools/list |
Cada herramienta registrada con su nombre, descripción y esquema de entrada |
resources/list |
Recursos legibles |
prompts/list |
Prompts publicados, con sus argumentos |
Qué refleja la lista de herramientas
La lista se construye a partir de lo que está registrado en este sitio, lo cual depende de qué productos están activos. No varía en función del token.
Esa distinción importa a la hora de diagnosticar:
- Falta una herramienta por completo — su producto no está activo aquí. Las herramientas de WooCommerce necesitan WooCommerce; las herramientas de POM Theme necesitan el tema POM.
- Una herramienta aparece listada pero se niega a ejecutarse — una comprobación de ámbito, capacidad, puerta o esquema rechazó la llamada.
Así que un cliente puede ver una herramienta que no tiene permitido usar. El listado es descubrimiento, no autorización. Consulta Modelo de seguridad de MCP.
Esquemas de entrada
Cada herramienta anuncia un esquema JSON para sus argumentos. Los clientes lo usan para construir llamadas válidas, y el servidor exige los argumentos obligatorios antes de ejecutar nada.
Un cliente que se comporta bien no enviará una llamada a la que le falte un argumento obligatorio, porque el esquema le ha dicho qué se necesita. pom_ai_mcp_missing_argument suele significar que el cliente ignoró el esquema o que el asistente improvisó.
Recursos y prompts
Los recursos son elementos legibles a los que se accede por URI, que se listan con resources/list y se obtienen con resources/read. Consulta Recursos de MCP.
Los prompts son instrucciones listas para usar que el servidor publica para trabajos habituales: crear una página de aterrizaje, actualizar una página de builder sin romper su estructura, crear un modelo de contenido, crear plantillas. prompts/list los muestra y prompts/get devuelve uno con los argumentos aplicados.
Los prompts se filtran según lo que el llamador pueda usar: cada uno declara los ámbitos y la capacidad que necesita, de modo que un cliente solo ve aquellos que realmente podría ejecutar. Empezar a partir de un prompt publicado es más fiable que describir el mismo trabajo desde cero. Consulta Recetas de prompts.
Límites de velocidad durante el descubrimiento
Las llamadas de listado cuentan contra el límite de lectura como cualquier otra petición. Un cliente que vuelve a listar de forma agresiva puede limitarse a sí mismo; los clientes que se comportan bien listan una vez por sesión y guardan en caché.
Cuando falla el descubrimiento
| Síntoma | Causa |
|---|---|
| El flujo nunca empieza | Las URL de .well-known devuelven un 404 — los enlaces permanentes bonitos no están configurados |
401 incluso con un token |
La cabecera Authorization se está eliminando aguas arriba |
| El cliente no puede registrarse | OAuth está desactivado, o el registro está limitado a 5 por minuto |
| Una lista de herramientas vacía | Productos inactivos, o la respuesta fue interceptada |
| HTML en lugar de JSON | Una capa de seguridad está interceptando las rutas |
Ejecuta primero los diagnósticos desde el panel de ajustes de MCP. Obtiene ambos documentos de metadatos y el endpoint de estado desde el propio servidor e informa del tipo de contenido, de si el cuerpo se analizó como JSON y de si apareció HTML — lo que distingue un problema de configuración de un problema del cliente en un solo paso.