Plugins de agente

Agent Plugins es un estándar abierto y neutral respecto al proveedor para empaquetar componentes reutilizables, servidores MCP incluidos, en plugins portables. Este repositorio incluye un manifest Agent Plugins 1.0 en su raíz: plugin.json nombra el plugin y su versión, y el mcp.json que lo acompaña es la configuración del servidor MCP que un host compatible arranca. Para los hosts que aún leen el formato anterior de Open Plugins, .plugin/plugin.json apunta al mismo mcp.json, de modo que ambas generaciones de hosts instalan lo mismo.

Qué clientes

El proyecto documenta Cursor, Claude Code, VS Code y OpenCode como hosts compatibles. La distribución y la instalación quedan fuera de la propia especificación, así que el comando exacto depende de tu host y de su versión; la forma que documenta el proyecto es:

# Cursor / Claude Code (cuando lo soporte tu versión)
/plugin install jmrplens/gitlab-mcp-server

La instalación trae el manifest y el mcp.json a tu host. Suministrar el token es un paso aparte, explicado más abajo, porque el manifest no puede llevarlo.

Qué ejecuta el plugin

El mcp.json incluido tiene una única entrada stdio que ejecuta la imagen Docker publicada, así que Docker tiene que estar instalado y en ejecución:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "gitlab": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITLAB_URL",
        "-e", "GITLAB_TOKEN",
        "-e", "GITLAB_MCP_SKIP_TLS_VERIFY",
        "-e", "GITLAB_MCP_TOOL_SURFACE",
        "ghcr.io/jmrplens/gitlab-mcp-server:latest"
      ]
    }
  }
}

El archivo real reenvía dieciocho variables con el mismo patrón -e NOMBRE. Un -e NOMBRE a secas copia la variable al contenedor desde el entorno en el que corre el propio docker, y solo cuando está definida ahí, así que las que no definas no cuestan nada y el servidor aplica su valor por defecto:

Variable	Obligatoria	Valor si no se define
`GITLAB_URL`	No	`https://gitlab.com`; defínela para una instancia autogestionada
`GITLAB_TOKEN`	Sí	ninguno: un token de acceso personal (`api`, o `read_api` para las acciones que GitLab acepta con él)
`GITLAB_MCP_SKIP_TLS_VERIFY`	No	`false`
`GITLAB_MCP_TOOL_SURFACE`	No	`dynamic` (las alternativas son `meta` e `individual`)
`GITLAB_MCP_CAPABILITY_SURFACE`	No	`full` (`minimal` conserva solo el manifiesto `gitlab://tools`)
`GITLAB_MCP_META_PARAM_SCHEMA`	No	`opaque` (las alternativas son `compact` y `full`)
`GITLAB_MCP_TIER`	No	detectado a partir de la licencia, después de los planes de los namespaces y después, en GitLab.com, de los grupos de nivel superior de los que el token es miembro, con `free` como último recurso
`GITLAB_MCP_READ_ONLY`	No	`false`
`GITLAB_MCP_SAFE_MODE`	No	`false`
`GITLAB_MCP_EMBEDDED_RESOURCES`	No	`true`
`GITLAB_MCP_EXCLUDE_TOOLS`	No	vacío: no se excluye nada
`GITLAB_MCP_IGNORE_SCOPES`	No	`false`
`GITLAB_MCP_UPLOAD_MAX_FILE_SIZE`	No	`2GB`
`GITLAB_MCP_ALLOWED_IMPORT_DIRS`	No	vacío: ningún directorio aparte de los siempre permitidos
`GITLAB_MCP_RATE_LIMIT_RPS`	No	`0`: sin límite de peticiones
`GITLAB_MCP_RATE_LIMIT_BURST`	No	`40`
`GITLAB_MCP_CLIENT_COMPAT`	No	`auto`
`GITLAB_MCP_LOG_LEVEL`	No	`info`

Qué hace cada una está en Configuración, y la referencia de variables de entorno da los valores que acepta cada una.

Dos detalles de esa entrada son esenciales:

El -i de docker run. El comando por defecto de la imagen deduce el transporte a partir de la entrada estándar, y -i es lo que coloca ahí una tubería. Sin él, el contenedor recibe /dev/null, lo interpreta como que nadie le habla, arranca un listener HTTP y un cliente stdio espera indefinidamente la respuesta a initialize. Mantenlo si copias esta entrada al JSON propio de un cliente.
La especificación de Agent Plugins arranca todas las entradas automáticamente y no tiene variantes por runtime, y por eso la entrada incluida usa Docker: es el único comando que se comporta igual en todas las plataformas.

La imagen se descarga en la primera ejecución y se reutiliza después. Sobre la política de descarga y cómo actualizarla, consulta Actualizar y desinstalar.

Cómo llega el token al servidor

Un token no puede viajar dentro de mcp.json. La especificación (§9.2) expande exactamente dos marcadores, ${PLUGIN_ROOT} y ${PLUGIN_DATA}, y dice que cualquier otro texto con forma de marcador debe quedarse literal, así que escribir "GITLAB_TOKEN": "${GITLAB_TOKEN}" le entrega al servidor esa cadena exacta en vez de tu token. También deja al host elegir el entorno base (§9.1): un cliente «MAY inherit, omit, or sanitize ambient variables», es decir, puede heredar, omitir o sanear las variables del entorno ambiente. Cómo llega GITLAB_TOKEN lo decide, por tanto, tu host:

El host hace visible la variable al subproceso del plugin. Define GITLAB_TOKEN (y GITLAB_URL para una instancia autogestionada) como documente tu host; las entradas -e la reenvían entonces al contenedor.

Pones tú el valor en la copia local del plugin instalado. Localiza el directorio del plugin instalado desde la interfaz de plugins de tu host o la salida de la instalación (habitualmente en .agents/plugins/gitlab-mcp-server/) y añade un bloque env a su mcp.json:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "gitlab": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITLAB_TOKEN", "ghcr.io/jmrplens/gitlab-mcp-server:latest"],
      "env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Si el servidor devuelve un fallo de autorización justo después de instalar, el token no llegó: comprueba cuál de las dos vías sigue tu host.

¿Prefieres el binario nativo en lugar de Docker?

Instala el plugin y después edita el mismo mcp.json local sustituyendo el command y los args de Docker por la ruta a un binario instalado por cualquier otro canal (binario nativo, Homebrew, npm, PyPI o NuGet):

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "gitlab": {
      "type": "stdio",
      "command": "/usr/local/bin/gitlab-mcp-server",
      "env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

La cuestión del token es la misma de antes: o el host expone la variable o la escribes tú en este archivo.

Para un despliegue HTTP en segundo plano no uses una entrada stdio. Ejecuta la imagen en modo HTTP y configura el cliente con "type": "http" y una URL como http://localhost:8080/mcp, como se describe en Modo servidor HTTP.

Configura tu cliente

En este canal el mcp.json del plugin es la configuración del cliente: el host lo lee y arranca la entrada. La forma mínima que funciona es la del bloque env mostrado arriba (el comando Docker, GITLAB_TOKEN y GITLAB_URL solo para una instancia autogestionada).

En un host sin soporte de plugins, la misma entrada Docker pegada en la configuración propia del cliente funciona igual; las rutas de archivo y las formas de cada cliente están en las pestañas por cliente del Inicio rápido, y la imagen en sí se documenta en la página de Docker.

Actualizar y desinstalar

La versión del manifest se estampa con cada release, pero lo que el plugin arranca realmente es la etiqueta de imagen latest, y docker run solo descarga cuando la imagen no está en local (su opción --pull usa por defecto missing). Un plugin instalado hace semanas sigue ejecutando la imagen que descargó el primer día hasta que la refresques:

docker pull ghcr.io/jmrplens/gitlab-mcp-server:latest

El siguiente arranque usa la imagen nueva. El servidor nunca comprueba si hay actualizaciones ni reemplaza su propio binario; aquí es Docker quien lo gestiona. Para fijar una versión en lugar de seguir latest, cambia la etiqueta en tu mcp.json local a ghcr.io/jmrplens/gitlab-mcp-server:3.2.0 y actualízala a mano.

Para desinstalar, quita el plugin como documente tu host (su interfaz o comando de plugins), borra la copia local de mcp.json si escribiste un token en ella, y libera la imagen si nada más la usa:

docker rmi ghcr.io/jmrplens/gitlab-mcp-server:latest

El resto de canales se comparan en la vista general de instalación.

Mantenido por José Manuel Requena PlensGitHub LinkedIn Mastodon Google Scholar Todos los proyectos