Servidores MCP

Agent Plugins define un formato mcp.json cerrado que los clientes asignan a su configuración MCP nativa. La especificación de Model Context Protocol sigue siendo la referencia para el comportamiento de MCP en el protocolo y para su ciclo de vida.

Documento de configuración

mcp.json se encuentra en la raíz del plugin y solo contiene $schema y mcpServers como campos de nivel superior:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "validator": {
      "type": "stdio",
      "command": "./bin/validator",
      "args": ["--data", "${PLUGIN_DATA}/validator"],
      "env": {
        "CONFIG": "${PLUGIN_ROOT}/config.json"
      },
      "cwd": "${PLUGIN_ROOT}"
    },
    "deployment-api": {
      "type": "streamable-http",
      "url": "https://deploy.example.com/mcp",
      "headers": {
        "X-Tenant": "public-tenant"
      }
    }
  }
}

Transportes

Un cliente conforme que admita MCP es compatible al menos con uno de estos transportes: stdio o streamable-http. Se recomienda que admita ambos. La compatibilidad con sse es opcional. El cliente usa el transporte declarado para el primer intento de conexión. Agent Plugins no define un comportamiento alternativo si ese intento falla.

Comandos y rutas de stdio

command es un único token de ejecutable, no un comando de shell. Puede ser un nombre de ejecutable simple que se resuelva mediante las reglas de búsqueda de la plataforma o una ruta relativa al plugin que empiece por ./. La expansión de marcadores de posición no se aplica a command.

Si se omite, cwd usa la raíz del plugin. Un cwd explícito es relativo al plugin, parte de ${PLUGIN_ROOT} o parte de ${PLUGIN_DATA}, y debe permanecer dentro del directorio correspondiente.

Variables del plugin

Los clientes proporcionan dos variables de entorno a los subprocesos stdio:

• PLUGIN_ROOT: ruta absoluta de la raíz del plugin resuelta por el sistema de archivos.
• PLUGIN_DATA: directorio de datos dedicado y escribible que se conserva al actualizar el plugin.

Los clientes expanden ambos marcadores de posición en args, los valores de env y cwd. La expansión es textual, de una sola pasada y no recursiva. No se aplica a las claves de entorno, command, las URL remotas ni los encabezados HTTP. Un plugin no puede sustituir las variables de entorno reservadas.

Conexiones remotas

Las URL remotas son URL HTTP o HTTPS absolutas sin información de usuario ni fragmentos. Los extremos que no sean de bucle invertido usan HTTPS. Los encabezados configurados son datos literales y visibles en el paquete; no deben contener credenciales ni secretos.

Agent Plugins 1.0.0 no define campos portátiles de OAuth ni referencias de credenciales. La autenticación sigue bajo el control del cliente.

Aislamiento de fallos

Un mcp.json de nivel superior no válido desactiva MCP para el plugin. Un servidor individual no válido o no disponible solo desactiva esa entrada. Los demás servidores, Agent Skills y extensiones de cliente continúan cargándose.

Descarga mcp.schema.json.