Entorno de ejecución MCP

Agent Plugins define cómo mcp.json selecciona un transporte y proporciona la configuración de ejecución. MCP define el entramado de mensajes, la inicialización, la negociación de capacidades, la autorización y el ciclo de vida.

Un cliente de Agent Plugins compatible con MCP debe admitir al menos uno de estos transportes: stdio o Streamable HTTP. Se recomienda que admita ambos. La compatibilidad con el antiguo HTTP+SSE es opcional.

Modelo de configuración

mcp.json contiene un objeto mcpServers cuyos miembros son servidores configurados de forma independiente. Cada entrada declara un type y solo los campos permitidos para ese transporte:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "local-tools": {
      "type": "stdio",
      "command": "./bin/server",
      "args": ["--data", "${PLUGIN_DATA}"]
    },
    "remote-tools": {
      "type": "streamable-http",
      "url": "https://tools.example.com/mcp"
    }
  }
}

Consulta todos los campos y restricciones en la referencia de servidores MCP para autores de plugins.

Seleccionar el transporte declarado

El campo type selecciona el transporte para el primer intento de conexión; no es una sugerencia de URL independiente del transporte. Después de leer type, crea el transporte MCP correspondiente. Agent Plugins no define un comportamiento alternativo si el intento falla. Los clientes que implementen un método alternativo pueden seguir las indicaciones de compatibilidad con versiones anteriores de MCP.

Las respuestas y los flujos SSE usados dentro de Streamable HTTP siguen formando parte de streamable-http; son distintos del transporte HTTP+SSE obsoleto. Las redirecciones siguen sujetas al transporte seleccionado y a las reglas de reenvío de encabezados que aparecen más adelante.

Validar en dos etapas

Primero valida el mcp.json de nivel superior: JSON válido, $schema compatible, versión de la especificación del plugin coincidente, mcpServers obligatorio y ausencia de campos desconocidos de nivel superior. Un fallo de nivel superior desactiva MCP para ese plugin.

Después valida cada entrada de servidor según los requisitos de su type declarado. Un transporte desconocido, un campo desconocido o un campo de transporte ausente o no válido solo invalida esa entrada. Omítela sin desactivar las entradas válidas del mismo nivel ni otros tipos de componentes. El schema canónico expone #/$defs/server para este fin.

Iniciar servidores stdio

• Trata command como un único token de ejecutable y pasa args por separado.
• Resuelve los comandos simples mediante las reglas de búsqueda de ejecutables de la plataforma.
• Resuelve un comando que empiece por ./ con respecto a la raíz del plugin y aplica el límite de contención. Los argumentos y valores de entorno siguen siendo cadenas opacas aunque parezcan rutas.
• Usa la raíz del plugin como valor predeterminado de cwd.
• Crea un directorio PLUGIN_DATA dedicado y escribible antes de iniciar el servidor, y consérvalo al actualizar el plugin.
• Superpone el env configurado al entorno base elegido por el cliente. Después, establece al final los valores PLUGIN_ROOT y PLUGIN_DATA controlados por el cliente.
• Expande las variables del plugin únicamente en args, los valores de env y cwd.

El cliente puede heredar, omitir o depurar variables del entorno general. Los plugins portátiles no pueden depender de variables del entorno general no especificadas ni de que el PATH configurado afecte a la resolución de comandos simples.

Tras iniciar el servidor, sigue los requisitos de transporte stdio y ciclo de vida de MCP.

Conectar servidores remotos

Valida la URL y los encabezados literales antes de establecer la conexión. Nunca reenvíes encabezados configurados a un origen distinto mediante redirecciones o eventos de extremo SSE antiguos sin la autorización explícita del usuario.

Sigue los requisitos de transporte Streamable HTTP, ciclo de vida y autorización de MCP. Agent Plugins no define campos portátiles de OAuth ni referencias de credenciales; el descubrimiento de autorización, el almacenamiento de credenciales y la interacción con el usuario están bajo el control del cliente. Un fallo de autenticación es un fallo de conexión, no una configuración de paquete no válida.

Fallos en tiempo de ejecución

Si un servidor no puede iniciarse, conectarse, autenticarse o completar el protocolo de enlace MCP, continúa cargando los demás servidores y componentes. Informa del fallo cuando resulte práctico.