Documentación de complementos de Claude Code: qué son, cómo instalarlos y cuándo usar MCP en su lugar

Si buscas la documentación de complementos de Claude Code, la respuesta breve es esta: los complementos son la capa de empaquetado para las extensiones de Claude Code. Un complemento puede agrupar skills, agentes, hooks, servidores MCP, servidores LSP y monitores en una sola unidad instalable, mientras que MCP sigue siendo la capa de conexión de herramientas subyacente. Si buscaste “mcp plugin” o “doc plugin”, normalmente esta es la distinción que la documentación quiere que hagas: los complementos distribuyen la configuración, MCP conecta las herramientas y la documentación de referencia explica la forma técnica de cada pieza.

Claude Code ahora tiene suficiente superficie de extensión como para que la terminología se vuelva confusa rápidamente. “Complemento” se usa a menudo como abreviatura de todo, incluso cuando la característica real en juego es un skill, un hook o un servidor MCP. Esa confusión importa porque los pasos de instalación, el modelo de seguridad y la carga de mantenimiento son diferentes para cada uno.

Antes de entrar en la configuración, una nota práctica para equipos que quieren más flexibilidad de backend de la que ofrece un flujo de trabajo de solo modelos cerrados: la capa de extensión de Claude Code es independiente del modelo que ejecutas detrás. Eso significa que puedes mantener la misma configuración de complementos, skills y MCP mientras enrutas la inferencia a través de un modelo de código de pesos abiertos en Novita AI, como qwen/qwen3-coder-480b-a35b-instruct, que es una opción creíble para trabajo real en repositorios cuando quieres más control de costos sin renunciar a las herramientas agénticas.

Lo que la documentación actual enfatiza

La documentación actual de Claude Code separa cuatro cosas con mucha claridad:

• complementos, que empaquetan extensiones reutilizables;
• MCP, que conecta Claude Code a herramientas y fuentes de datos externas;
• skills y subagentes, que contienen comportamiento reutilizable;
• hooks, que automatizan acciones en eventos del ciclo de vida.

Eso significa que muchas búsquedas de “documentación de complementos de Claude Code” en realidad están pidiendo la referencia de complementos, el flujo de descubrimiento/instalación, o la documentación de MCP que explica cómo funciona la conectividad de herramientas. La documentación actual también expone flujos de instalación y distribución basados en marketplaces, por lo que puedes instalar complementos preconstruidos en lugar de conectar manualmente cada componente.

Qué son realmente los complementos de Claude Code

La documentación actual de Anthropic define los complementos como la capa de distribución y reutilización de las extensiones de Claude Code. En la práctica, eso significa que un complemento es un directorio autocontenido con un manifiesto y componentes de extensión opcionales, como:

• skills
• agentes
• hooks
• configuración de MCP
• configuración de LSP
• binarios auxiliares
• ajustes por defecto

Por eso la documentación oficial de complementos importa incluso si lo que realmente quieres es un skill reutilizable o un andamiaje MCP de un solo comando. El complemento suele ser lo que instalas, pero el comportamiento que te interesa vive dentro de los componentes empaquetados.

La consecuencia más importante es la nomenclatura. Los skills de los complementos tienen espacio de nombres, por lo que un comando de un complemento se ve así:

/my-plugin:hello

Ese espacio de nombres no es cosmético. Evita colisiones entre complementos que envían comandos con nombres similares.

Complementos vs MCP vs Skills vs Hooks

Aquí es donde la mayoría de los desarrolladores pierden tiempo en la documentación.

Usa este atajo:

Característica	Qué hace	Mejor caso de uso
Complemento	Empaqueta y distribuye extensiones	Reutilizar la misma configuración entre proyectos o compañeros de equipo
MCP	Conecta Claude Code a herramientas y servicios externos	GitHub, Notion, bases de datos, control de navegador, APIs internas
Skill	Le da a Claude conocimiento reutilizable o un flujo de trabajo	Listas de verificación de revisión, flujos de despliegue, estilo de la casa, prompts repetibles
Hook	Se ejecuta automáticamente en eventos del ciclo de vida	Lint después de ediciones, bloquear comandos riesgosos, activar notificaciones

Muchas preguntas sobre “complementos de Claude Code” son en realidad preguntas sobre MCP. Si tu objetivo es “conectar Claude Code a Jira” o “permitir que Claude consulte nuestra base de datos”, no estás buscando principalmente una función de complemento. Estás buscando un servidor MCP, que puede instalarse directamente o empaquetarse dentro de un complemento. En la práctica, eso significa que muchas búsquedas de un MCP plugin son en realidad búsquedas del servidor correcto más la ruta de empaquetado o instalación adecuada.

Por eso también es útil la descripción general de funciones en la documentación de Anthropic: separa explícitamente los complementos de MCP y de los skills. Los complementos son el envoltorio. MCP es la conexión externa. Los skills son las instrucciones reutilizables. Los hooks son la capa de automatización.

Desde una perspectiva de la pila de Novita, este también es el lugar más limpio para separar el razonamiento de la ejecución. Si estás construyendo un flujo de trabajo personalizado adyacente a Claude Code en torno a herramientas MCP, la API de LLM de Novita puede manejar la capa de razonamiento para el uso de herramientas, mientras que Novita Agent Sandbox maneja la capa de ejecución aislada para código, comandos de shell y efectos secundarios de las herramientas. Esa división se corresponde naturalmente con el límite de “el modelo decide” versus “el runtime ejecuta” que la documentación de complementos y MCP está describiendo realmente.

Cuándo debes usar un complemento

Usa un complemento cuando al menos una de estas condiciones sea cierta:

• quieres la misma personalización de Claude Code en múltiples repositorios;
• quieres que los compañeros de equipo instalen una sola cosa en lugar de copiar archivos .claude/ manualmente;
• quieres empaquetado versionado y compartible para skills, hooks o configuraciones MCP;
• planeas distribuir la extensión a través de un marketplace.

No recurras a un complemento primero si solo estás experimentando en un solo repositorio. La documentación de Anthropic todavía recomienda comenzar con configuración independiente de .claude/ para iteración rápida. Esa es la ruta de menor fricción para flujos de trabajo específicos de un proyecto.

En otras palabras:

• la configuración independiente es mejor para experimentación local;
• los complementos son mejores para portabilidad y distribución.

La forma más rápida de instalar un complemento existente

Si ya conoces el nombre del complemento y el marketplace, la documentación actual apunta al flujo de comando de barra desde dentro de Claude Code.

Por ejemplo, la documentación de MCP de Anthropic usa esta ruta de instalación para el complemento oficial mcp-server-dev:

/plugin install mcp-server-dev@claude-plugins-official

Si Claude Code informa que falta el marketplace, agrégalo primero:

/plugin marketplace add anthropics/claude-plugins-official

Luego vuelve a ejecutar el comando de instalación.

Después de la instalación, verifica si Claude te dice que recargues los complementos. Si es así, ejecuta:

/reload-plugins

Ese paso de recarga importa más de lo que parece. Es una razón común por la que los desarrolladores piensan que un complemento “no funcionó” cuando los archivos están presentes pero los comandos no están activos en la sesión actual.

Cómo crear tu propio complemento de Claude Code

Si quieres crear tu propio complemento, la documentación actual de complementos describe un inicio rápido sencillo:

1. Crea un directorio para el complemento.
2. Añade .claude-plugin/plugin.json.
3. Añade un directorio de extensión compatible como skills/, agents/, hooks/, u otro.
4. Inicia Claude Code con --plugin-dir durante el desarrollo.

El ejemplo útil más pequeño es un complemento que incluya un solo skill. La documentación de Anthropic muestra un manifiesto más una carpeta skills/<name>/SKILL.md. El manifiesto define la identidad del complemento, y el skill se convierte en un comando con espacio de nombres.

Durante el desarrollo, el flujo de prueba canónico es:

claude --plugin-dir ./my-first-plugin

Luego invoca el skill desde dentro de Claude Code:

/my-first-plugin:hello

Un detalle que es fácil pasar por alto: solo plugin.json pertenece dentro de .claude-plugin/. Tus directorios skills/, agents/ y hooks/ permanecen en la raíz del complemento, no anidados bajo .claude-plugin/.

Por qué la documentación sigue mencionando MCP dentro de las guías de complementos

Porque un complemento puede incluir una configuración de MCP.

Esto es útil cuando tienes un servicio interno que todos los ingenieros de tu equipo necesitan que Claude Code alcance. En lugar de decirle a todos que configuren manualmente el mismo servidor MCP, puedes empaquetar esa configuración con el resto de tu flujo de trabajo de Claude Code.

Eso no hace que MCP sea obsoleto. Solo cambia la forma en que se entrega el servidor.

Piénsalo de esta manera:

• MCP responde: “¿Cómo habla Claude con este sistema externo?”
• Un complemento responde: “¿Cómo distribuimos esa configuración limpiamente?”

Si estás diseñando una plataforma interna para desarrolladores, esa distinción ahorra mucho trabajo de configuración duplicado.

Cuándo MCP es el mejor punto de partida

Empieza con MCP, no con un complemento, cuando el requisito principal sea el acceso externo:

• rastreadores de incidencias
• herramientas de monitoreo
• Slack
• Notion
• bases de datos
• automatización de navegador
• servicios HTTP internos

La documentación actual de MCP de Anthropic muestra cuatro modos comunes de conexión:

• servidores HTTP remotos
• servidores SSE remotos
• servidores stdio locales
• servidores WebSocket remotos

Para la mayoría de los servicios en la nube, HTTP es el transporte recomendado. SSE todavía está documentado, pero Anthropic lo marca como obsoleto donde HTTP está disponible.

Si solo necesitas conectar un servicio para ti mismo, claude mcp add suele ser el lugar más limpio para comenzar. Envuélvelo en un complemento más tarde si la configuración demuestra ser reutilizable.

MCP le da a Claude Code una forma de alcanzar herramientas, pero no reemplaza un runtime de ejecución seguro cuando una de esas herramientas necesita ejecutar código, tocar archivos o ejecutar comandos. En esa configuración, la API de LLM de Novita es el backend de razonamiento que decide cuándo y cómo llamar a las herramientas, mientras que Novita Agent Sandbox es el entorno de ejecución más seguro para el lado del flujo de trabajo que ejecuta código. Si tu complemento o servidor MCP está exponiendo ejecución remota de código, automatización de navegador o ayudantes respaldados por shell, esa separación es más que higiene de arquitectura. Es la diferencia entre “Claude puede llamar a esta herramienta” y “esta herramienta se ejecuta en un runtime aislado en lugar de en el portátil de un ingeniero o en un host compartido”.

Una regla práctica de decisión

Si todavía no estás seguro de qué página de documentación necesitas realmente, usa esta regla:

• “Quiero que Claude Code haga algo de la misma manera en cada sesión.” Empieza con CLAUDE.md o un skill.
• “Quiero que Claude Code hable con otro sistema.” Empieza con MCP.
• “Quiero que esta configuración sea fácil de reutilizar o compartir.” Empaquétala como complemento.
• “Quiero que algo se ejecute automáticamente en un evento.” Usa un hook.

Eso es más útil que memorizar nombres de funciones porque se asigna directamente al problema que estás resolviendo.

Dónde encaja esto en un flujo de trabajo real

Si la configuración del complemento o MCP es solo una pieza de una pila de agentes más grande, combínala con ¿Qué son los agentes de codificación?, Runtime de agente vs intérprete de código, y Sandbox de servidores MCP: servidores MCP aislados con control de archivos, secretos y red. Eso te da la cadena completa desde la planificación hasta el acceso a herramientas y la ejecución aislada.

Un buen flujo de trabajo de complementos para equipos reales

Para la mayoría de los equipos, la progresión más limpia se ve así:

1. Crea un prototipo del flujo de trabajo en .claude/ o con comandos directos de claude mcp add.
2. Conserva solo las partes que demuestren ser útiles en el trabajo real.
3. Empaqueta esas partes en un complemento con un manifiesto claro y skills con espacio de nombres.
4. Compártelo a través de un marketplace o una ruta de distribución interna.

Esto evita el modo de fallo más común: convertir cada idea en un complemento antes de que alguien sepa si vale la pena mantener el flujo de trabajo.

Si tu equipo está combinando Claude Code con un backend de modelo alternativo, esta también es la etapa en la que Novita AI puede ser útil operativamente. La capa de complementos y MCP permanece igual, mientras que el enrutamiento de modelos puede moverse a la API de LLM de Novita para sesiones intensivas de codificación que no necesitan un modelo cerrado premium en cada paso. Esa división suele ser más simple que rediseñar la propia pila de extensiones.

Errores comunes en la configuración de complementos de Claude Code

Estos son los errores que más tiempo hacen perder:

Tratar cada extensión como un complemento

A veces la respuesta correcta es un skill simple o una configuración directa de servidor MCP. Empaquetar demasiado pronto añade mantenimiento.

Poner archivos en el directorio equivocado

plugin.json va en .claude-plugin/. Los skills y hooks no.

Olvidar el espacio de nombres

Un skill de complemento se invoca con el prefijo del complemento, no como un comando global.

Omitir la recarga después de la instalación

Si Claude te dice que ejecutes /reload-plugins, hazlo antes de asumir que la instalación falló.

Usar un complemento cuando la necesidad real es MCP

Si el problema central es la conectividad de herramientas, concéntrate en MCP primero y empaqueta después.

Conclusión

La documentación de complementos de Claude Code tiene más sentido cuando dejas de tratar “complemento” como el único concepto de extensión. Los complementos son la capa de distribución. Los skills contienen instrucciones reutilizables. Los hooks automatizan eventos del ciclo de vida. MCP conecta Claude Code a sistemas externos.

Ese marco hace que el resto de la documentación sea mucho más fácil de navegar. Si tu objetivo es una configuración rápida, empieza con la unidad de trabajo más pequeña que resuelva el problema. Añade empaquetado solo cuando valga la pena reutilizar la configuración.

Preguntas frecuentes

¿Los complementos de Claude Code son lo mismo que los servidores MCP?

No. Los servidores MCP son la capa de conexión para herramientas y servicios externos. Los complementos son una capa de empaquetado que puede incluir configuración de MCP junto con skills, hooks, agentes y otras extensiones de Claude Code.

¿Cómo instalo un complemento de Claude Code?

Desde dentro de Claude Code, usa el comando /plugin install con el nombre del complemento y del marketplace. Si el marketplace no está presente, agrégalo con /plugin marketplace add ..., luego recarga los complementos si Claude te lo pide.

¿Debo usar un complemento o solo archivos .claude/?

Usa archivos .claude/ para iteración rápida específica de un proyecto. Usa un complemento cuando la configuración deba reutilizarse entre proyectos, compartirse con compañeros de equipo o distribuirse a través de un marketplace.

¿Cuándo debo usar MCP en lugar de un complemento?

Usa MCP primero cuando tu objetivo principal sea el acceso externo a sistemas como GitHub, Jira, Notion, Slack o APIs internas. Si estás comparando una guía de MCP plugin con una página de documentación de complementos, trata la guía de MCP como la referencia de conexión de herramientas y la página de documentación de complementos como la referencia de empaquetado. Empaqueta esa configuración como complemento más tarde solo si necesitas una reutilización y distribución más limpias.

¿Pueden los complementos de Claude Code funcionar con backends de modelos que no sean de Anthropic?

Sí. La capa de extensión y el backend de modelos son preocupaciones separadas. En la práctica, eso significa que puedes mantener la misma configuración de complementos y MCP de Claude Code mientras enrutas la inferencia a través de un proveedor compatible como Novita AI para flujos de trabajo de codificación compatibles.

Artículos recomendados

• Complementos de Claude Code: cómo las herramientas MCP extienden Claude Code con capacidades externas
• Reglas de Claude Code: cómo escribir CLAUDE.md y gestionar el contexto de codificación agéntico
• Construye un servidor MCP de ejecución remota de código con Novita Sandbox y la librería mcp-use

Fuentes consultadas el 31 de agosto de 2026: Descripción general de funciones de Claude Code, Documentación de complementos de Claude Code, Documentación de MCP de Claude Code y Biblioteca de modelos de Novita AI.