Añade servidores de Model Context Protocol a Gemini CLI con el comando gemini mcp add o con una entrada escrita a mano en settings.json. Consulta configuraciones que funcionan con stdio, SSE y HTTP en streaming, además de OAuth, filtrado de herramientas, ajustes de confianza y las comprobaciones que solucionan un servidor atascado en Disconnected.
Gemini CLI es útil desde el momento en que lo instalas. Se vuelve mucho más útil cuando puede acceder a tu gestor de incidencias, tu base de datos o una carpeta de archivos de diseño sin que tengas que pegar nada en el prompt. El puente es el Model Context Protocol, y cada puente es un servidor MCP. Gemini CLI puede comunicarse con servidores que se ejecutan como procesos locales, con servidores detrás de un endpoint HTTP normal y con endpoints SSE de streaming más antiguos. Ofrece dos formas de registrarlos: un comando gemini mcp add o unas pocas líneas en settings.json.
Este artículo recorre ambas rutas con comandos reales y después aborda las partes que suelen fallar: ámbitos, secretos, filtrado de herramientas, OAuth y el temido estado Disconnected. Cada flag y campo que aparece aquí procede de la documentación oficial de MCP de Gemini CLI, y cuando el comportamiento cambia entre versiones, lo indico.
💡 Respuesta rápida: ejecuta
gemini mcp add -s user <name> <command-or-url>y, dentro de la CLI, escribe/mcp. El servidor debería aparecer como conectado y listar sus herramientas.
Al iniciarse, Gemini CLI lee los servidores configurados, se conecta a cada uno y pregunta qué ofrece. El servidor responde con una lista de herramientas, y cada herramienta tiene un nombre, una descripción y un esquema JSON para sus entradas. El modelo ve esas herramientas junto a las integradas (lectura de archivos, comandos de shell, búsqueda web) y las llama cuando un prompt las necesita.
Un servidor puede exponer tres tipos de cosas:
La mayoría de servidores solo ofrecen herramientas, y ahí es donde la configuración da su fruto. Todo lo que sigue trata de conectar esas herramientas de forma segura.
Cada entrada de servidor usa exactamente uno de los tres transportes. El campo que definas determina cuál usa la CLI.
| Transporte | Campo de configuración | Flag de la CLI | Ideal para |
|---|---|---|---|
| Stdio | command (más args) | por defecto, o --transport stdio | Servidores locales que la CLI lanza con npx, node o python3 |
| SSE | url | --transport sse | Servidores remotos más antiguos que aún exponen un endpoint /sse |
| HTTP en streaming | httpUrl | --transport http | Servidores remotos actuales y servicios alojados |
Con stdio, la CLI inicia el proceso y se comunica con él a través de la entrada y salida estándar. Eso significa que un servidor nunca debe imprimir texto suelto en stdout. Los logs deben ir a stderr, o el flujo del protocolo se rompe y el servidor se desconecta.
La elección suele venir decidida. Si el servidor es un paquete o un script en tu equipo, usa stdio. Si está en una URL y el proveedor ofrece HTTP y SSE, elige HTTP, ya que SSE es el transporte más antiguo y existe sobre todo para servidores que todavía no han migrado.
Si gemini aún no está en tu PATH, instálalo con npm install -g @google/gemini-cli. Después, el comando add es la vía más rápida.
gemini mcp add [options] <name> <commandOrUrl> [args...]
El nombre va primero, luego el ejecutable o la URL y, por último, los argumentos que necesite el servidor. Estas son las opciones que más usarás:
| Flag | Qué hace |
|---|---|
-s, --scope | user o project. El valor por defecto es project. |
-t, --transport | stdio (por defecto), sse o http |
-e, --env | Define una variable de entorno como NAME=value. Se puede repetir. |
-H, --header | Define una cabecera HTTP como "Authorization: Bearer abc123". Se puede repetir. |
--timeout | Tiempo de espera de la petición en milisegundos |
--trust | Omite las confirmaciones de herramientas para este servidor |
--description | Una nota breve que aparece en los listados |
--include-tools, --exclude-tools | Listas de permitidos y bloqueados separadas por comas |
Un script local, guardado para tu usuario para que funcione en cualquier carpeta:
gemini mcp add -s user -e ISSUES_TOKEN='$ISSUES_TOKEN' issues node /home/me/mcp/issues-server.js
Un servidor alojado por HTTP en streaming, con una cabecera bearer:
gemini mcp add --transport http --header "Authorization: Bearer abc123" docs-search https://mcp.example.com/mcp
Un endpoint SSE más antiguo:
gemini mcp add --transport sse legacy-events http://localhost:8080/sse
La gestión del día a día usa la misma familia de comandos:
gemini mcp list
gemini mcp disable issues --session
gemini mcp enable issues
gemini mcp remove issues -s user
El flag --session de enable y disable cambia el estado solo para la sesión actual. Sin él, la elección se guarda en ~/.gemini/mcp-server-enablement.json.
💡 Cuidado con las comillas. En el primer ejemplo, las comillas simples mantienen
$ISSUES_TOKENcomo marcador de posición. Con comillas dobles, tu shell lo expande primero y el token real acaba ensettings.json. Abre el archivo después de añadir un servidor y compruébalo.
💡 Los argumentos que empiezan por guion, como
npx -y, pueden confundirse con opciones de la CLI al procesar los flags. Para los servidores lanzados así, escribe la entrada ensettings.json.
El comando add escribe el JSON por ti. Editar ese JSON directamente te da todos los campos, mantiene tu configuración revisable en un pull request y facilita copiar un bloque que funciona a un compañero.
~/.gemini/settings.json. Te acompaña a cualquier carpeta..gemini/settings.json dentro del repositorio. Haz commit y todo el equipo tendrá los mismos servidores.El archivo del proyecto se lee después del de usuario, así que gana cuando ambos definen el mismo nombre de servidor. Ten en cuenta que gemini mcp add escribe en el ámbito de proyecto a menos que pases -s user.
Este archivo registra un servidor por transporte:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"],
"timeout": 30000
},
"issues": {
"command": "node",
"args": ["./mcp/issues-server.js"],
"cwd": "/home/me/work/tracker",
"env": { "ISSUES_TOKEN": "$ISSUES_TOKEN" },
"includeTools": ["search_issues", "get_issue"]
},
"docs-search": {
"httpUrl": "https://mcp.example.com/mcp",
"headers": { "Authorization": "Bearer abc123" },
"timeout": 15000
},
"legacy-events": {
"url": "http://localhost:8080/sse"
}
}
}
Esto es lo que hace cada campo:
| Campo | Tipo | Notas |
|---|---|---|
command, args, cwd | string, string[], string | Ajustes de lanzamiento para servidores stdio |
url | string | Endpoint SSE |
httpUrl | string | Endpoint HTTP en streaming |
headers | objeto | Cabeceras personalizadas para url o httpUrl |
env | objeto | Variables de entorno que se pasan al servidor |
timeout | número | Tiempo de espera de la petición en milisegundos. El valor por defecto es 600000, es decir, diez minutos. |
trust | booleano | Por defecto false. Cuando es true, se omiten las confirmaciones de herramientas. |
includeTools | string[] | Solo se habilitan estas herramientas |
excludeTools | string[] | Estas herramientas están deshabilitadas. Esta lista prevalece sobre includeTools. |
oauth, authProviderType | objeto, string | Ajustes de autenticación, explicados más abajo |
Dentro del bloque env, Gemini CLI expande $NAME y ${NAME} en todas las plataformas, y %NAME% en Windows. Una variable que no está definida se convierte en una cadena vacía, sin aviso. El resultado es un servidor que arranca y luego falla en la autenticación, lo que parece un error del servidor cuando en realidad es un error de escritura en el nombre de una variable.
Un archivo de proyecto normalmente se confirma en el repositorio, así que referencia variables y nunca pegues un secreto en él. La expansión está documentada para el bloque env, así que si quieres un token en headers, confirma que tu versión de la CLI lo expande, o mantén esa entrada en el ámbito de usuario, donde nunca llega al control de versiones.
Conectar un servidor le da al modelo un nuevo conjunto de capacidades. Decide cuánto de eso quieres antes del primer prompt.
Supón que un servidor expone search_issues, get_issue y delete_issue. Quieres las dos primeras y nunca la tercera:
"issues": {
"command": "node",
"args": ["./mcp/issues-server.js"],
"includeTools": ["search_issues", "get_issue"],
"excludeTools": ["delete_issue"]
}
excludeTools tiene prioridad, así que una herramienta incluida en ambas listas queda desactivada. También puedes filtrar servidores completos desde el nivel superior de settings.json:
"mcp": {
"allowed": ["issues", "filesystem"],
"excluded": ["experimental-server"]
}
Cuando mcp.allowed está definido, solo se conectan los servidores que aparecen allí. mcp.excluded bloquea los que enumeres.
Por defecto, Gemini CLI pide permiso antes de ejecutar una herramienta. Definir "trust": true, o pasar --trust al añadir un servidor, desactiva todas las confirmaciones de ese servidor. Es razonable para un servidor de solo lectura que tú mismo escribiste. Es mala idea para cualquier cosa que pueda escribir archivos, enviar mensajes o ejecutar comandos, porque un mal prompt podría activarla sin que lo veas antes.
Muchos servidores alojados requieren iniciar sesión. Dentro de la CLI, ejecuta /mcp auth para listar los servidores que admiten OAuth y luego autentica uno por su nombre:
/mcp auth docs-search
La CLI abre tu navegador, completa el flujo y guarda el token en ~/.gemini/mcp-oauth-tokens.json. Los tokens caducados se renuevan automáticamente. Cuando un servidor no publica sus datos de OAuth, añade tú mismo un bloque oauth:
"oauth": {
"enabled": true,
"clientId": "gemini-cli-client",
"authorizationUrl": "https://auth.example.com/oauth/authorize",
"tokenUrl": "https://auth.example.com/oauth/token",
"scopes": ["mcp:read"]
}
No todos los servidores usan OAuth. Un token bearer fijo va en headers, como se mostró antes. Para servicios de Google Cloud, el campo authProviderType acepta google_credentials, además de service_account_impersonation junto con targetServiceAccount. Para servidores detrás de Identity-Aware Proxy, añade targetAudience con el ID de cliente de OAuth. El proveedor por defecto funciona para la mayoría de los demás servidores, así que no toques el campo a menos que necesites uno de estos.
Edita el archivo y luego ejecuta /mcp reload. Si la CLI sigue mostrando los ajustes antiguos después, reinicia la sesión.
| Comando | Resultado |
|---|---|
/mcp o /mcp list | Servidores, estado de la conexión y herramientas |
/mcp desc | La misma lista con las descripciones de las herramientas |
/mcp schema | Descripciones más el esquema de entrada de cada herramienta |
/mcp auth <server> | Inicia OAuth para un servidor |
/mcp reload | Vuelve a conectar todos los servidores y actualiza sus herramientas |
/mcp enable, /mcp disable | Activa o desactiva un servidor para la sesión |
Fuera de una sesión, gemini mcp list te da la misma vista general de conexiones desde la shell.
Las versiones recientes muestran las herramientas MCP con un nombre completamente cualificado con la forma mcp_<server>_<tool>. Una herramienta search_issues en un servidor llamado issues pasa a ser mcp_issues_search_issues. Los artículos más antiguos describen un prefijo server__tool, que se usa cuando dos servidores exponen una herramienta con el mismo nombre. Si ves un estilo en un tutorial y el otro en tu pantalla, lo más probable es que tengas una versión distinta.
Se derivan dos consecuencias prácticas. Primero, nombra tus servidores con guiones, no con guiones bajos. El nombre se divide en el primer guion bajo después de mcp_, y un guion bajo dentro del nombre de un servidor puede confundir las reglas de política. Segundo, rara vez necesitas el nombre completo en un prompt. Pregunta en lenguaje natural, por ejemplo:
Use the issues server to list open bugs labelled regression, newest first.
La CLI muestra qué herramienta planea llamar y pide confirmación, a menos que definas trust.
Empieza por las comprobaciones básicas, porque resuelven la mayoría de casos:
command y el args exactos en una terminal normal. Si falla ahí, fallará en la CLI.cwd existe y que node, npx o python3 está en tu PATH.--debug y lee los errores de conexión./mcp reload después de cada cambio y reinicia la CLI si los ajustes antiguos parecen seguir activos.Este caso le pasa a muchísima gente constantemente. En una carpeta que no has marcado como confiable, Gemini CLI no se conecta a ningún servidor MCP e ignora por completo el .gemini/settings.json del proyecto. Se lee tu archivo de ámbito de usuario, pero los servidores del proyecto simplemente no aparecen.
Ejecuta /permissions dentro de la CLI para confiar en la carpeta, o responde al cuadro de confianza la primera vez que la abras. La elección se guarda en ~/.gemini/trustedFolders.json. Para las ejecuciones sin interfaz gráfica, la documentación enumera el flag --skip-trust y la variable GEMINI_CLI_TRUST_WORKSPACE=true.
Algunos fallos no dan ningún error:
/mcp schema.timeout para servidores remotos inestables, o auméntalo para trabajos lentos como consultas grandes.env. Se expandió a una cadena vacía.includeTools y excludeTools, y la lista mcp.allowed del nivel superior.💡 Una prueba rápida de cordura: añade primero un servidor stdio pequeño, consigue que se conecte y solo entonces añade los servidores remotos. Cada servidor nuevo es una cosa más que puede fallar, así que añádelos de uno en uno.
Puedes usar un modelo de lenguaje para redactar las partes tediosas de una configuración, y Picasso IA aloja varios modelos Gemini que puedes abrir en el navegador. Este es un flujo de trabajo que funciona bien:
settings.json y el comando gemini mcp add equivalente. Indica al modelo que use referencias $VARIABLE en lugar de secretos literales.command, url o httpUrl, y cada nombre en includeTools debe coincidir con lo que imprime /mcp desc./mcp reload.💡 Trata el borrador como una primera versión. Un modelo puede inventarse un campo que suena bien. Las tablas de este artículo y la documentación oficial son tu fuente de verdad.
Una buena configuración de MCP es solo la mitad de un flujo de trabajo de desarrollo bien organizado. La otra mitad es el material que lo rodea: banners del README, ilustraciones de tutoriales, tarjetas para redes sociales y fotos para la entrada del blog que explica tu configuración.
Picasso IA te permite generar esas imágenes en pocos minutos. Prueba Seedream 4.5 para escenas fotorrealistas detalladas, GPT Image 2 cuando necesites texto nítido dentro de una imagen, o Nano Banana 2 Lite para borradores rápidos. Escribe un prompt corto, genera unas cuantas variaciones y quédate con la que encaje en tu página.
Elige un proyecto que tengas abierto hoy, escribe un prompt que describa su banner y mira qué sale. Explora todos los modelos disponibles en picassoia.com/en/all-models y empieza por el que coincida con el estilo que tienes en mente.
Elige tu idioma
