Objetivo del tema
Comprender qué es MCP en Qwen Code, cómo permite conectar herramientas y servicios externos, qué formas de transporte existen, cómo se configura en settings.json y qué buenas prácticas de seguridad conviene aplicar antes de habilitar servidores MCP en un proyecto real.
Este tema se apoya en la documentación oficial disponible al 11 de abril de 2026, especialmente en Connect Qwen Code to tools via MCP, MCP servers with Qwen Code y la referencia de settings.json.
MCP significa Model Context Protocol. Es un protocolo pensado para que un modelo o un agente pueda descubrir y usar herramientas externas de manera estandarizada.
En términos simples, MCP actúa como un puente entre Qwen Code y otros sistemas:
Sin MCP, Qwen Code trabaja con sus herramientas integradas y con el contexto del proyecto. Con MCP, en cambio, puede ampliar su radio de acción y operar sobre herramientas diseñadas por terceros o por tu propia organización.
MCP no es “una función extra” del CLI. Es el mecanismo que convierte a Qwen Code en una plataforma extensible capaz de conectarse con herramientas ajenas al repositorio.
La documentación oficial enumera varios casos de uso. Llevados a un lenguaje más práctico, con MCP podés pedirle a Qwen Code que:
Esto es muy importante pedagógicamente: Qwen Code deja de ser solo un asistente que mira archivos locales y pasa a ser un agente que puede interactuar con un ecosistema más amplio.
Un servidor MCP es una aplicación que expone herramientas y, en algunos casos, recursos o prompts, a través del protocolo MCP. Qwen Code se conecta a ese servidor, descubre qué herramientas ofrece y las incorpora a su registro global de tools.
La documentación para desarrolladores explica tres capacidades principales de un servidor MCP:
En la práctica, Qwen Code se enfoca sobre todo en la ejecución de herramientas, pero el concepto de recursos también es parte del protocolo y explica por qué MCP resulta tan flexible.
La documentación técnica describe dos capas importantes dentro de la integración con MCP:
mcpServers, se conecta a cada servidor y obtiene la definición de sus herramientasTambién aclara que Qwen Code sanea y valida esquemas para mantener compatibilidad con la API y que resuelve conflictos de nombres si dos servidores publican tools con el mismo identificador.
Esto explica un punto que suele sorprender al principio: un servidor MCP no se usa “a mano” desde el prompt del sistema operativo, sino que primero debe ser descubierto e integrado por Qwen Code.
Qwen Code carga los servidores MCP desde la clave mcpServers en settings.json. Las dos ubicaciones más habituales son:
.qwen/settings.json para el proyecto actual~/.qwen/settings.json para todos los proyectos del usuarioEn el curso ya vimos que Qwen Code tiene varias capas de configuración. Para MCP, lo más común es definir servidores a nivel de proyecto cuando pertenecen al dominio del repositorio, y a nivel de usuario cuando son herramientas generales que querés reutilizar en muchos proyectos.
La guía oficial propone un flujo inicial muy claro:
qwen mcp add --transport http my-server http://localhost:3000/mcp
qwen mcp
Luego conviene reiniciar Qwen Code en el mismo proyecto y pedirle al agente que use herramientas provenientes de ese servidor.
Este paso de reinicio es importante porque la sesión interactiva necesita redescubrir las herramientas disponibles. Si agregás el servidor y seguís usando una sesión anterior, podrías pensar que la configuración “no funcionó” cuando en realidad todavía no se recargó.
Qwen Code soporta tres mecanismos de transporte para conectarse con servidores MCP.
| Transporte | Cuándo usarlo | Campo principal |
|---|---|---|
stdio |
Cuando el servidor corre como proceso local, script o CLI en tu propia máquina. | command |
http |
Recomendado para servicios remotos o servidores MCP en la nube. | httpUrl |
sse |
Para servidores heredados que todavía usan Server-Sent Events. | url |
La documentación actual recomienda preferir HTTP sobre SSE cuando el servidor soporta ambas opciones. stdio, por su parte, es ideal cuando el servidor es un proceso local de confianza que querés lanzar directamente desde la máquina.
Cuando el servidor corre como proceso local, la forma más típica de darlo de alta es:
qwen mcp add python-server python server.py --port 8080
Conceptualmente, esto le dice a Qwen Code: “cuando quieras conectarte a este servidor MCP, ejecutá este comando local con estos argumentos y hablá con él por entrada y salida estándar”.
Este esquema es común para herramientas internas, prototipos, scripts del equipo o integraciones que todavía no se publicaron como servicio de red.
Si el servidor vive fuera de tu máquina, lo habitual es usar transporte HTTP:
qwen mcp add --transport http http-server https://api.ejemplo.com/mcp/
Y si necesitás encabezados de autenticación:
qwen mcp add --transport http secure-http https://api.ejemplo.com/mcp/ --header "Authorization: Bearer abc123"
Este patrón es muy frecuente cuando el equipo expone herramientas corporativas detrás de una API o cuando una plataforma cloud ofrece un endpoint MCP listo para consumir.
settings.jsonAunque el CLI ofrece comandos para administrar MCP, conviene entender la estructura de configuración que queda persistida:
{
"mcpServers": {
"mi-servidor": {
"command": "node",
"args": ["servidor-mcp.js"],
"env": {
"API_KEY": "$MI_API_KEY"
},
"cwd": "./tools/mcp",
"timeout": 30000,
"trust": false
}
}
}
La documentación oficial indica que al menos uno de estos campos debe existir en cada servidor:
commandurlhttpUrlSi se definen varios a la vez, la precedencia actual es httpUrl, luego url y finalmente command.
Además del transporte, hay varios campos que conviene entender bien:
| Campo | Función |
|---|---|
args |
Argumentos de línea de comandos para un servidor stdio. |
env |
Variables de entorno para el proceso del servidor. |
cwd |
Directorio de trabajo desde el cual se ejecuta el servidor. |
headers |
Cabeceras HTTP para servidores remotos. |
timeout |
Límite de tiempo de las llamadas al servidor. |
trust |
Omite confirmaciones para ese servidor. Debe usarse con mucho criterio. |
description |
Descripción del servidor para mostrar contexto o facilitar administración. |
La mayoría de errores iniciales con MCP vienen de tres fuentes: ruta equivocada en command, endpoint incorrecto en httpUrl o variables de entorno faltantes en env.
Una de las funciones más útiles de Qwen Code es que no obliga a exponer todas las herramientas de un servidor. Podés aplicar filtros por servidor usando:
includeToolsexcludeToolsEjemplo:
{
"mcpServers": {
"filteredServer": {
"command": "python",
"args": ["-m", "mi_servidor_mcp"],
"includeTools": ["safe_tool", "file_reader", "data_processor"],
"timeout": 30000
}
}
}
La documentación deja claro que excludeTools tiene prioridad sobre includeTools. Esto es útil cuando querés partir de una lista reducida y además bloquear alguna herramienta puntual.
mcp.allowed y mcp.excludedAdemás de configurar cada servidor, Qwen Code permite definir reglas globales bajo la clave mcp:
{
"mcp": {
"allowed": ["mi-servidor-confiable"],
"excluded": ["servidor-experimental"]
}
}
Estas listas actúan sobre los nombres de los servidores, no sobre cada tool individual. Son útiles para restringir qué servidores se conectan, aunque la propia documentación advierte que no deben tratarse como una barrera de seguridad perfecta.
Si necesitás control fuerte a nivel organizacional, no alcanza con una simple lista por nombre. La documentación sugiere controlar la configuración en capas superiores del sistema.
MCP aumenta mucho el poder operativo del agente, pero también amplía la superficie de riesgo. Por eso conviene diferenciar varias capas:
trust: true se omiten confirmaciones para ese servidorLa regla práctica más sensata es simple: no marques un servidor como confiable solo porque funciona. Marcá como confiable únicamente un servidor cuyo origen, comportamiento y herramientas entendés bien.
La documentación de configuración explica que si varios servidores exponen una tool con el mismo nombre, Qwen Code resuelve el conflicto agregando un prefijo basado en el alias del servidor. De este modo evita colisiones entre herramientas equivalentes provenientes de fuentes distintas.
Esto importa bastante en organizaciones grandes, donde podría existir por ejemplo una tool llamada search en más de un servidor. Qwen Code necesita distinguirlas sin perder trazabilidad.
/Un detalle muy interesante de la documentación para desarrolladores es que un servidor MCP no solo puede exponer herramientas. También puede exponer prompts predefinidos que luego aparecen en Qwen Code como comandos slash.
La idea es potente: un equipo puede publicar prompts reutilizables desde un servidor y hacer que todos los usuarios los invoquen de forma uniforme, sin copiar texto manualmente.
/poem-writer --title="Qwen Code" --mood="reverente"
/poem-writer "Qwen Code" reverente
En un entorno real no usarías un prompt de poemas, claro, pero sí algo como:
/generar-reporte-incidente 12345
/resumir-cambios-release 2.7.0
/documentar-endpoint pagos
Esto enlaza MCP con otro tema ya visto en el curso: los comandos del CLI. La diferencia es que en este caso el comando no vive localmente como un markdown del proyecto, sino que lo provee un servidor externo.
La documentación actual destaca tres comandos principales para administración:
qwen mcp add --transport http my-server http://localhost:3000/mcp
qwen mcp
qwen mcp remove my-server
qwen mcp abre una interfaz interactiva para:
Esto es útil porque evita editar JSON a mano para cada prueba, especialmente al principio del aprendizaje o cuando se está depurando una integración.
La documentación de extensiones indica que una extensión también puede aportar servidores MCP mediante su propio manifiesto. En ese caso, los servidores se cargan al iniciar igual que los definidos en settings.json.
Además, si una extensión y settings.json definen un servidor con el mismo nombre, la configuración de settings.json tiene prioridad. Eso permite que el proyecto o el usuario sobreescriban detalles sin tener que modificar la extensión original.
| Problema | Causa probable | Primer paso razonable |
|---|---|---|
| El servidor aparece desconectado | URL, comando o credenciales incorrectas. | Revisar qwen mcp, logs y valores de headers o env. |
| No se descubren herramientas | El servidor no responde correctamente o el filtro las está ocultando. | Verificar includeTools, excludeTools y compatibilidad del esquema. |
| La tool existe pero no se ejecuta | Timeout bajo, error interno del servidor o permisos insuficientes. | Aumentar timeout y revisar logs del servidor. |
| Las variables no se resuelven | La variable de entorno no existe en el contexto donde corre Qwen Code. | Confirmar entorno efectivo del proceso y no asumir que coincide con el shell. |
| El agente usa una herramienta equivocada | Hay herramientas similares en varios servidores o descripciones poco claras. | Reducir exposición, renombrar mejor o filtrar herramientas por servidor. |
Para trabajar bien con MCP en proyectos reales, conviene seguir estas reglas:
includeTools para limitar el conjunto expuesto.trust: true por comodidad si todavía no entendés el impacto.La calidad de una integración MCP no depende solo de que “conecte”, sino de que quede bien delimitada, sea auditable y resulte fácil de mantener.
MCP es la puerta de entrada para conectar Qwen Code con herramientas externas de forma estructurada. Gracias a este protocolo, el agente puede descubrir tools, ejecutarlas, usar prompts remotos y colaborar con sistemas más allá del repositorio local.
En este tema vimos las ideas esenciales:
stdio, http o sse.mcpServers dentro de settings.json.Con esta base, el siguiente paso natural es profundizar en integraciones y extensiones más avanzadas, donde MCP se combina con otros mecanismos de personalización de Qwen Code.