Integraciones de Claude Code MCP: cómo se conectan las herramientas a los agentes de codificación de IA

1. Introducción

Un agente de codificación sin acceso a herramientas externas no puede hacer mucho. Puede explicar el código, sugerir cambios o escribir un parche. Pero si quieres que compruebe un repositorio, llame a una API o lea un archivo de registro, tiene que ir más allá de su ventana de contexto. Aquí es donde la mayoría de las configuraciones comienzan a fallar.

He visto a los equipos crear estas conexiones desde cero. Puede haber un script de Python en un lugar y un contenedor personalizado en otro. Una integración usa JSON a través de HTTP, otra ejecuta comandos a través de una CLI y otra depende de un adaptador antiguo de un hackathon. Esta configuración funciona con unas cuantas herramientas, pero a medida que añades más, las cosas se complican. Los permisos se vuelven inconsistentes y la depuración se hace más difícil.

Claude Code está pasando de ser solo un asistente a convertirse en un agente conectado. Resulta mucho más útil cuando puede acceder a archivos, herramientas de desarrollo y sistemas externos. Pero si no hay una forma estándar de conectarlo todo, terminas con integraciones frágiles que pueden fallar inesperadamente.

Esto es lo que aborda MCP.

El Protocolo de contexto modelo proporciona una forma estándar de poner las herramientas a disposición de los modelos. En lugar de conectar cada herramienta a cada agente, se utiliza un protocolo de detección compartido. Esto no resuelve todos los problemas, pero hace que la pregunta pase de «cómo puedo conectar esto» a «cómo administro lo que está conectado».

2. ¿Qué son las integraciones de MCP en Claude Code?

El MCP es un protocolo, no un producto. Esto es importante porque da forma a la forma en que Claude Code funciona entre bastidores.

El protocolo de contexto modelo especifica cómo las herramientas se describen a sí mismas en un modelo y cómo las llama el modelo. Estandariza el intercambio: descubrimiento, esquema, solicitud y respuesta. No implementa la herramienta en sí misma. No gestiona el control de acceso. Solo proporciona el contrato.

Cuando mencionamos las integraciones de MCP en Claude Code, nos referimos a las herramientas que Claude puede descubrir y usar a través del protocolo. El modelo no está vinculado a cada punto final. En su lugar, utiliza una interfaz estructurada, comprende los parámetros y utiliza la herramienta como parte de su flujo de trabajo.

Por ejemplo, supongamos que quieres que Claude cree un problema en GitHub cuando encuentre un error durante la revisión del código. Sin MCP, tendrías que escribir código personalizado para gestionar el resultado de Claude, iniciar sesión en GitHub y realizar la llamada a la API. Con MCP, basta con registrar una integración de GitHub que proporcione a la herramienta create_issue parámetros como el repositorio, el título, el cuerpo y las etiquetas. A continuación, Claude puede buscar y usar esa herramienta directamente.

Las integraciones de MCP hacen más que conectar a Claude con las herramientas, sino que definen cómo Claude reconoce esas herramientas e interactúa con ellas desde el principio.

3. Cómo funciona MCP en Claude Code

Cuando corre, Claude solo conoce las herramientas disponibles a través de MCP. La forma en que interactúa con ellas sigue una secuencia establecida.

Este paso ocurre antes de que Claude interactúe con cualquier cosa. Una herramienta se registra en un servidor MCP e incluye su nombre, descripción y esquema de entrada. El esquema ayuda al modelo a entender la herramienta. Si el registro no está claro, es posible que Claude haya elegido la herramienta equivocada.

Un lector de archivos puede exponer un parámetro de ruta. Una integración de GitHub puede mostrar el repositorio, la rama y el issue_id, mientras que una herramienta de registro puede usar service_name, time_range y severity_filter.

Descubrimiento de herramientas

Cuando Claude se conecta, envía una solicitud de herramientas o listas:

{
  "method": "tools/list"
}

El servidor devuelve las herramientas disponibles y sus esquemas. Esta lista se convierte en el conjunto de posibles acciones de Claude. Claude no está adivinando, está leyendo una interfaz claramente definida.

Invocación

Cuando Claude necesita una herramienta, envía una solicitud call_tool con argumentos. Supongamos que Claude encuentra un problema de seguridad durante la revisión. Podría invocar la integración de GitHub de la siguiente manera:

{
  "method": "call_tool",
  "params": {
    "name": "github_create_issue",
    "arguments": {
      "repository": "acme/payment-service",
      "title": "SQL injection vulnerability in user input handler",
      "body": "Found unsanitized user input in src/handlers/payment.py line 142...",
      "labels": ["security", "high-priority"]
    }
  }
}

Si los argumentos son incorrectos o las definiciones de las herramientas no están claras, las cosas pueden fallar en esta etapa.

Gestión de respuestas

La herramienta se ejecuta independientemente del modelo y devuelve un resultado. Claude lee este resultado y continúa. A veces el resultado es claro, pero otras veces es confuso o incompleto. De cualquier manera, afecta a lo que sucede a continuación.

Este ciclo de registro, descubrimiento, invocación y respuesta es la forma en que MCP opera dentro de Claude Code.

4. Tipos de integraciones de MCP

Todas las integraciones de MCP utilizan el mismo protocolo, pero no todas funcionan de la misma manera. Aparecen diferencias en la forma en que manejan el estado, en la previsibilidad de sus respuestas y en la cantidad de contexto que Claude tiene que gestionar.

Integraciones de sistemas de archivos

Son del tipo más simple. Claude lee y escribe archivos en ciclos rápidos. Esto es rápido y, por lo general, predecible, pero también frágil. Si falta la ruta de un archivo o la escritura está incompleta, el flujo de trabajo puede interrumpirse sin errores evidentes. He visto cómo los agentes se quedan atascados porque la lectura de un archivo arroja un valor vacío en lugar de un error. Integraciones de repositorios

Estas incluyen GitHub, GitLab y herramientas similares. Claude puede leer las solicitudes de cambios, comprobar las confirmaciones, crear problemas e introducir cambios. Esto es poderoso, pero puede ser arriesgado. Si los permisos no se configuran correctamente, un agente podría combinar código de forma que no debería. Ten cuidado con los permisos, ya que leer las solicitudes de cambios no es lo mismo que escribir en las sucursales.

Integraciones de API

Se trata de servicios externos a los que se accede a través de HTTP. Son más estructurados pero menos indulgentes. Tienes que lidiar con las llamadas de red, la autenticación, los límites de velocidad y los tiempos de espera. Los desajustes de esquema pueden aparecer en mitad de una ejecución. He corregido casos en los que Claude no dejaba de intentar una llamada de Jira que fallaba debido a un error de validación de un campo oculto.

Registro y observabilidad

Claude puede consultar registros, seguimientos o métricas. En su mayoría, se trata de operaciones de lectura con grandes cantidades de datos. El principal desafío es hacer la pregunta correcta. Una herramienta que devuelva 10 000 líneas de registro no es útil, pero una que permita filtrar por intervalo de tiempo, gravedad y servicio es mucho mejor.

Integraciones de bases de datos

Estos están en buen estado y conllevan más riesgos. Claude crea consultas basadas en esquemas que puede que no comprenda del todo. En este caso, la precisión es más importante que la velocidad. La mayoría de los equipos los configuran como de solo lectura.

Todos utilizan el mismo protocolo, pero su comportamiento en la práctica puede variar mucho.

5. Arquitectura MCP en Claude Code

El sistema funciona bien porque cada capa permanece separada. Si las combinas, rápidamente se hace más difícil entenderlas y administrarlas.

La capa de agente es el propio Claude. Determina lo que quieres, decide qué información necesita y si se debe usar una herramienta. Claude no dirige nada directamente, sino que planifica, elige y delega tareas.

La capa MCP actúa como límite del protocolo y estandariza la forma en que se describen y llaman a las herramientas. Para Claude, cada herramienta, ya sea un lector de archivos, una base de datos o una API externa, aparece como una interfaz estructurada, porque MCP hace que todas tengan el mismo aspecto.

La capa de herramientas es donde realmente ocurren las cosas. Se ejecutan los comandos, se modifican los archivos y se realizan llamadas a la API. Aquí es donde se producen los efectos reales.

Claude piensa sin interactuar directamente con el sistema. Las herramientas se encargan de la ejecución sin tomar decisiones. MCP convierte las intenciones de Claude en acciones reales.

Esta configuración explica algunas opciones de diseño. ¿Por qué Claude no llama directamente a la API de GitHub? No debería necesitar saber que es GitHub. En su lugar, solo ve una herramienta llamada create_issue con un esquema. La autenticación, los límites de frecuencia y la gestión de errores se producen en la capa de herramientas, detrás del protocolo.

6. Limitaciones de las integraciones de Claude Code MCP

MCP hace que la conectividad sea más limpia. No hace que esté listo para la producción por sí solo.

Sin gobierno centralizado

MCP pone a disposición las herramientas, pero no controla quién puede ver qué en diferentes equipos o entornos. A medida que añades más integraciones, esto se convierte en un desafío. Es posible que un agente vea demasiadas herramientas, mientras que otro vea muy pocas. No hay un lugar central para mantener la coherencia.

Por ejemplo, si tiene tres implementaciones de Claude, una para la revisión del código, otra para la respuesta a incidentes y otra para la documentación, cada una necesita un acceso diferente a las herramientas. El agente de revisión del código no debería ver las herramientas de base de datos de producción y la respuesta a los incidentes no debería escribir en el repositorio principal. Con el MCP nativo, tienes que configurar cada implementación por separado y esperar que nada se desincronice.

Brechas de seguridad

El acceso a las herramientas se basa en las credenciales utilizadas. Muchas configuraciones de MCP utilizan permisos de nivel de servicio demasiado amplios. Si los restringe, los flujos de trabajo pueden interrumpirse. Si los deja abiertos, aumenta el riesgo. El protocolo no resuelve este problema.

Sin observabilidad

Claude llama a las herramientas y sigue adelante, dejando invisible lo que pasó en el medio. Se desconoce qué herramienta se seleccionó, por qué, con qué argumentos y la respuesta. Sin rastros, la depuración se convierte en conjeturas. He pasado horas intentando averiguar por qué un agente eligió una herramienta en particular, solo para darme cuenta de que no había ningún registro de esa decisión.

Problemas de escalado

Se puede gestionar una pequeña cantidad de integraciones, pero tener docenas se complica. Los nombres varían, los esquemas son diferentes y los equipos definen las herramientas a su manera. Claude tiene que trabajar con esta configuración incoherente, lo que perjudica la fiabilidad. Por ejemplo, si tanto github_create_issue como gh_new_issue están registrados, Claude tiene que adivinar cuál usar.

Exposición fragmentada de herramientas

No hay un límite claro para lo que debe ver un agente. Las listas de herramientas se hacen más largas con el tiempo. Algunas herramientas se vuelven anticuadas, mientras que otras son demasiado potentes. Una lista desordenada empeora el rendimiento y el control.

7. Por qué los equipos van más allá de las integraciones de MCP nativas

MCP administra las conexiones, pero no administra el control.

A medida que los equipos pasan de unas pocas integraciones a una producción completa, sus necesidades cambian. Las herramientas deben gestionarse, no solo encontrarse. ¿Qué agente puede usar qué herramienta? ¿En qué condiciones? ¿Con qué límites? El MCP nativo no responde estas preguntas con claridad.

Aquí es donde las pasarelas se vuelven útiles. No solo suponen una sobrecarga adicional, sino que ayudan a gestionar la creciente complejidad.

Hay una puerta de enlace entre los servidores Claude y MCP. Restringe la visibilidad de la herramienta en función de la identidad del agente. Aplica la autenticación antes de que las solicitudes lleguen a las herramientas posteriores. Aplica límites de velocidad, registra las invocaciones y rechaza las infracciones de las políticas.

La auditoría funciona de la misma manera. Cuando los agentes interactúan con los sistemas de producción, por ejemplo, al crear problemas, consultar las bases de datos o leer los registros, los equipos necesitan saber qué se hizo, quién lo hizo y por qué. Sin esto, la depuración y el cumplimiento son reactivos y solo se descubren los problemas una vez que se producen.

Una integración simple se convierte en algo más: una capa de control entre los agentes y las herramientas que da forma al funcionamiento del acceso en situaciones reales.

8. Mejores prácticas para las integraciones de MCP

Las integraciones de MCP funcionan mejor cuando se tratan como interfaces, no como atajos.

El acceso a la herramienta Scope es estrecho.

El acceso debe ajustarse a la tarea. Si una integración solo necesita leer los metadatos del repositorio, no debe tener credenciales que puedan eliminar ramas. Esto suena obvio, pero con frecuencia se ignora porque los permisos más amplios son más rápidos de configurar. Al principio es más rápido, pero es posible que pases semanas arreglando cosas después de que un agente elimine algo que no debería.

Limite la visibilidad de las herramientas por agente

El modelo solo debe ver lo que necesita. Si un agente solo lee archivos y busca problemas, no necesita acceder a los controles de implementación ni escribir en la base de datos. Un menor número de opciones implica menos errores.

Diseñe definiciones de herramientas claras.

Nombres explícitos. Responsabilidades limitadas. Esquemas predecibles. Si una herramienta hace cinco cosas, Claude deduce demasiado. Las buenas integraciones son aburridas. Cada herramienta hace una cosa de forma limpia.

Por ejemplo, en lugar de tener una herramienta de operaciones de GitHub con muchos parámetros, divídela en GitHub_READ_PR, GitHub_CREATE_ISSUE y GitHub_add_comment. Esto hace que el propósito de cada herramienta sea claro y limitado.

Prevenir la expansión

Tener demasiadas herramientas similares dificulta la elección de la correcta y ralentiza la depuración. Es mejor tener un conjunto de herramientas más pequeño y bien organizado que uno grande y desordenado. Revise los registros de las herramientas con regularidad, elimine las herramientas no utilizadas y combine las herramientas superpuestas.

9. Integraciones de MCP frente a API frente a SDK

Estos resuelven problemas relacionados en diferentes capas.

Las API son la interfaz básica en la mayoría de los sistemas, y los SDK facilitan su uso. MCP se suma a ambas, lo que convierte el acceso a las herramientas en un formato uniforme que los agentes pueden usar.

MCP no reemplaza a las API ni a los SDK. Tu integración con GitHub aún usa la API de GitHub. MCP solo estandariza la forma en que Claude encuentra y usa esa integración.

10. Conclusión

MCP pone orden en lo que solía ser un proceso complicado. Estandariza la forma en que los modelos exponen, descubren y utilizan las herramientas. Esto facilita la creación de agentes conectados.

Pero sigue siendo solo un punto de partida. No responde a las preguntas sobre el control, la visibilidad o las políticas. No decide qué agente accede a qué herramienta ni cómo se auditan las interacciones. Aquí es donde la arquitectura de su sistema debe evolucionar. Se pasa de las integraciones simples a añadir una capa gestionada delante de ellas. El MCP posibilita las conexiones, pero lo que construyas en torno a él decidirá si esas conexiones siguen siendo manejables.

Preguntas frecuentes

¿Qué ocurre cuando falla una llamada a la herramienta MCP?

Claude recibe la respuesta de error y decide cómo proceder. Podría volver a intentarlo, probar con otra herramienta o descubrir el error. El problema es que la gestión de errores varía según las integraciones. Algunas devuelven códigos estructurados. Otros devuelven mensajes vagos. Sin esquemas de error consistentes, la recuperación se vuelve impredecible.

¿Puedo restringir las herramientas que ve una implementación de Claude?

No a través del propio MCP. El protocolo gestiona el descubrimiento y la invocación. El control de acceso es externo. Configura cada servidor MCP por separado o agrega una puerta de enlace que filtra la visibilidad en función de la identidad del agente.

¿Cómo gestionan la autenticación las integraciones de MCP?

En la capa de herramientas, no en la capa de protocolo. Cada servidor MCP administra las credenciales de los servicios que contiene. Claude no ve esas credenciales. Solo llama a herramientas. Cada integración se asegura por separado.

¿Cuál es la sobrecarga de rendimiento de MCP?

Mínimo en la mayoría de los casos. El MCP supone una sobrecarga de protocolo para el descubrimiento y la invocación, pero la ejecución real se realiza independientemente de lo que utilice la herramienta (normalmente llamadas directas a la API o comandos locales). La sobrecarga está en la estandarización, no en la ruta de ejecución.

¿Cómo se depura una mala selección de herramientas?

Difícil sin observabilidad. Registra todas las respuestas de todas las herramientas o listas y todas las solicitudes de call_tool y, a continuación, reconstruye manualmente las decisiones. Una capa de puerta de enlace automatiza este registro y simplifica la depuración.

‍