Mejores Prácticas para Servidores y Clientes MCP

Cada práctica en esta página se remonta a un modo de fallo real cubierto en otra parte de esta sección: una herramienta que nunca apareció porque no estaba registrada, un cambio de esquema que rompió un cliente existente, un servidor compartido sin limitación de velocidad que un llamador podía agotar.

Utilice esto como una verificación previa al vuelo antes de mover un servidor del desarrollo local a cualquier entorno compartido o remoto.

Cómo Usar Esta Lista de Verificación

• Recórrela de arriba a abajo la primera vez que implemente un nuevo servidor, diseñando primero la herramienta/recurso y dejando las pruebas para el final.
• Vuelva a visitar las secciones C a E (transporte, autenticación, versionado) cada vez que cambie cómo o dónde se implementa un servidor.
• No todas las reglas se aplican a todos los servidores; una herramienta stdio puramente local no tiene una necesidad real de autenticación o limitación de velocidad.
• Trate un elemento no marcado como una brecha conocida, no como un bloqueo, pero una que debería poder explicar si se le pregunta.

A - Diseño de Herramientas, Recursos y Prompts

• Asigne a cada herramienta un nombre claro y orientado a la acción, y una cadena de documentación (docstring) que describa lo que hace y cualquier restricción en sus argumentos. Esto es lo que Claude y los desarrolladores humanos utilizan para decidir si llamarla y cómo hacerlo.
• Utilice sugerencias de tipo precisas o esquemas para cada argumento, incluidos conjuntos de valores fijos, en lugar de un str genérico. Un tipo vago produce un esquema que no proporciona al cliente una guía real sobre la entrada válida.
• Utilice una herramienta para cualquier cosa con efectos secundarios y un recurso para cualquier cosa que sean datos puramente de solo lectura. Mezclar ambos confunde cómo un cliente presenta la capacidad y cómo razona sobre la seguridad.
• Genere excepciones reales para los casos de fallo en lugar de devolver una cadena de error como si fuera un éxito. Una cadena devuelta parece un resultado válido para el cliente; una excepción se convierte en un error estructurado adecuado.
• Mantenga cada servidor enfocado en un conjunto coherente de capacidades relacionadas en lugar de una gran superficie de "todo vale". Un servidor con docenas de herramientas no relacionadas es más difícil de razonar tanto para Claude como para los mantenedores.

B - Ciclo de Vida de la Solicitud y Registro

• Verifique que cada manejador implementado esté realmente registrado, no solo escrito. Una función de herramienta que existe pero que nunca fue decorada es invisible para cualquier cliente conectado, la fuente más común de "mi herramienta no aparece".
• Confirme que la negociación de capacidades se completa con éxito antes de asumir que cualquier herramienta, recurso o prompt es accesible. Nada en la etapa de intercambio del ciclo de vida funciona hasta que la negociación se completa.
• Trate cada llamada a herramienta como independiente a menos que haya creado deliberadamente un estado con ámbito de sesión. El protocolo no garantiza el orden entre las llamadas; depender de la memoria implícita entre llamadas es una fuente común de errores sutiles.
• Mantenga el estado por sesión separado cuando un servidor maneja múltiples sesiones de cliente concurrentes. Mezclar el estado entre sesiones es un error de corrección, no solo de rendimiento.

C - Elección del Transporte

• Utilice stdio por defecto para el desarrollo local y herramientas de usuario único. No tiene configuración de red, ni puerto que administrar, y el bucle de reinicio más rápido posible mientras la superficie de la herramienta aún está cambiando.
• Pase a HTTP/SSE una vez que más de un cliente, máquina o equipo necesite acceder al mismo servidor. stdio inicia un proceso separado por cliente, lo que falla para el estado compartido o el acceso coordinado a un backend.
• Considere una migración de stdio a HTTP/SSE como un cambio de transporte, no una reescritura. Los manejadores de herramientas, recursos y prompts son agnósticos al transporte en ambos SDK oficiales; la migración se trata principalmente de agregar autenticación y cambiar la capa de conexión.

D - Autenticación y Control de Acceso

• Nunca exponga un servidor HTTP/SSE sin autenticación, incluso para lo que parece un despliegue interno o temporal. Cualquier cosa accesible a través de la red por partes que no confía plenamente necesita un límite delante de ella.
• Aplique la autenticación en la capa de conexión, antes de que se alcance el transporte MCP, no dentro de manejadores de herramientas individuales. Para cuando se ejecuta un manejador, la negociación ya ha expuesto el manifiesto de capacidades del servidor.
• Utilice hmac.compare_digest o una comprobación equivalente de tiempo constante para cualquier comparación de secretos. Una comparación ingenua == puede filtrar información de tiempo que ayuda a un atacante a adivinar un token válido.
• Elija la autenticación basada en tokens para un conjunto pequeño y conocido de clientes de confianza, y OAuth para una audiencia más amplia o de terceros. Adapte la complejidad del esquema a quién se conecta realmente en lugar de optar por la opción más pesada en todas partes.
• Termine TLS delante de cualquier despliegue HTTP/SSE. Enviar tokens o códigos OAuth a través de HTTP plano los expone a cualquiera que observe la ruta de red, lo que anula por completo el esquema de autenticación.

E - Limitación de Velocidad y Carga de Producción

• Clasifique los límites de velocidad por identidad de cliente resuelta, no por un único contador global. Un contador compartido permite que un llamador de alto volumen agote el límite para todos los demás clientes.
• Elija una estrategia de limitación de velocidad que coincida con la forma de su tráfico: ventana fija para tráfico simple y constante; ventana deslizante o cubo de tokens para tráfico de ráfagas legítimas. Una ventana fija demasiado rígida causa rechazos falsos justo en el límite de reinicio.
• Solo agregue limitación de velocidad una vez que un servidor sea realmente compartido. Agrega complejidad real que una herramienta stdio de usuario único no necesita soportar.
• Devuelva un error claro y distinguible cuando un cliente está limitado en velocidad, en lugar de un fallo genérico ambiguo. El llamador, o Claude, necesita reconocerlo como un límite de velocidad y retroceder, no reintentar ciegamente.

F - Versionado de Esquemas

• Agregue nuevos argumentos de herramienta como opcionales con valores predeterminados sensatos, nunca renombre ni elimine los existentes sin un plan. Los clientes existentes que llaman con la forma antigua fallarán la validación del esquema inmediatamente.
• Envíe cambios genuinamente incompatibles como un nuevo nombre de herramienta en lugar de mutar el existente. Forzar un cambio incompatible en el mismo nombre significa que cada cliente conectado tiene que actualizarse simultáneamente.
• Asigne a cualquier herramienta o campo obsoleto un aviso de deprecación visible en su descripción, con una ventana de eliminación definida. Una eliminación silenciosa rompe los clientes sin previo aviso.
• Trate los argumentos de la herramienta como un contrato público, con el mismo cuidado que aplicaría a una API pública, no a una firma de función interna. Los clientes que usted no controla dependen de la forma exacta que ha publicado.

G - Pruebas Antes del Despliegue

• Escriba pruebas unitarias que llamen directamente a las funciones de manejo de herramientas y recursos, cubriendo tanto la ruta feliz como al menos un fallo de validación por manejador. Retroalimentación rápida para la lógica de negocio sin la sobrecarga de la capa de protocolo.
• Escriba al menos una prueba de integración que inicie el servidor real y lo impulse a través de una sesión de cliente. Esta es la única capa que detecta una herramienta que está implementada correctamente pero nunca registrada.
• Pruebe que la entrada inválida se presenta como un error estructurado a través del cliente real, no solo dentro de la función probada unitariamente. Confirma que el fallo realmente llega al cliente limpiamente en lugar de bloquear el proceso del servidor.
• Agregue una prueba de integración que ejercite la autenticación cuando el servidor se implementa sobre HTTP/SSE. El token válido tiene éxito, el token faltante o inválido es rechazado; ambos necesitan cobertura antes de un despliegue remoto.
• Vuelva a ejecutar las pruebas de integración después de cualquier cambio de esquema para detectar una regresión contra clientes que usan la forma de argumento anterior. Las pruebas sirven como una red de seguridad para la disciplina de versionado en la sección F.

Preguntas Frecuentes

Relacionado

• Cómo los Servidores MCP Manejan las Solicitudes - el ciclo de vida detrás de las secciones A y B
• Comparación de Despliegue de MCP stdio vs HTTP/SSE - la decisión de transporte detrás de la sección C
• Autenticación de Servidores MCP Remotos - detalle completo detrás de la sección D
• Referencia de Esquemas de Herramientas MCP de Versionado y Limitación de Velocidad - detalle completo detrás de las secciones E y F
• Pruebas de Servidores MCP Antes del Despliegue - detalle completo detrás de la sección G

Versiones de Stack: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y los SDK actuales de Model Context Protocol en Python/TypeScript. Los nombres de los modelos, las versiones de los SDK y el protocolo MCP evolucionan rápidamente; verifique los detalles actuales en platform.claude.com/docs y modelcontextprotocol.io antes de confiar en ellos.