- Cómo Funciona la Configuración de MCP de Claude
- Agregar Servidores MCP en Claude Code
- Configuración de Servidores MCP en Claude Desktop
- Tipos de Transporte MCP: stdio vs SSE
- Cómo Razona Claude sobre las Herramientas MCP
- Ejecución de Herramientas en un Entorno Aislado (Sandbox)
- Usando la API LLM de Novita para el Razonamiento sobre el Uso de Herramientas MCP
- Problemas Comunes y Soluciones
- Preguntas Frecuentes (FAQ)
- Artículos Recomendados
La configuración de MCP de Claude conecta Claude Code o Claude Desktop con herramientas externas como bases de datos, ejecutores de código, APIs y servidores personalizados. Usa claude mcp add para Claude Code o edita la configuración JSON de Claude Desktop, luego verifica el transporte, el alcance y la lista de herramientas. Esta guía cubre ambos métodos de configuración, fallos comunes, el razonamiento sobre el uso de herramientas y la ejecución en entornos aislados.
Cómo Funciona la Configuración de MCP de Claude
MCP es un estándar abierto de Anthropic que proporciona a los modelos de lenguaje una forma uniforme de llamar a herramientas externas. Antes de MCP, cada aplicación de IA necesitaba código de integración personalizado para cada herramienta que quisiera usar. Con MCP, cualquier servidor compatible expone sus capacidades a través de un protocolo estándar de descubrimiento e invocación, y cualquier host compatible —incluyendo Claude— puede usarlas sin necesidad de trabajo de integración por herramienta.
En términos prácticos: cuando agregas un servidor MCP a Claude, le estás indicando al host de Claude dónde encontrar un conjunto de herramientas. Claude puede entonces listar esas herramientas durante una sesión y llamarlas por nombre cuando la tarea lo requiera. El servidor maneja la ejecución; Claude maneja el razonamiento sobre cuándo y cómo llamar.
Tres conceptos fundamentales sustentan MCP:
| Concepto | Qué es | Ejemplo |
|---|---|---|
| Herramienta (Tool) | Una función invocable expuesta por el servidor | run_python, query_db, list_models |
| Recurso (Resource) | Datos de solo lectura que el servidor pone a disposición como contexto | Un archivo, una fila de base de datos, un conjunto de datos |
| Prompt | Plantillas de instrucciones predefinidas incluidas con el servidor | Una descripción de tarea a nivel de sistema |
Para la mayoría de los desarrolladores, las herramientas son lo que más importa. Los recursos y los prompts se vuelven relevantes cuando estás construyendo un pipeline de agente más estructurado.
Agregar Servidores MCP en Claude Code
Claude Code expone la gestión de MCP a través del subgrupo de comandos claude mcp. Puedes agregar, eliminar y listar servidores sin tocar ningún archivo de configuración manualmente.
claude mcp add — la forma básica
claude mcp add <nombre> <comando> [args...]
Por ejemplo, para agregar un servidor MCP local de Python:
claude mcp add my-tools python /path/to/mcp_server.py
Esto registra un servidor llamado my-tools que ejecuta python /path/to/mcp_server.py usando transporte stdio. Claude Code inicia el proceso cuando comienzas una sesión y lo mantiene activo durante su duración.
Pasar variables de entorno
Muchos servidores MCP necesitan claves de API o URLs de endpoint. Usa --env para pasarlas en el momento del registro:
claude mcp add my-tools python /path/to/mcp_server.py \
--env API_KEY=tu_clave_aqui \
--env BASE_URL=https://api.example.com
Los valores se almacenan en la configuración de Claude Code y se inyectan en el proceso del servidor al inicio. No codifiques secretos directamente en el comando del servidor.
claude mcp add json — registrar desde una especificación JSON
Si ya tienes una especificación de servidor escrita como JSON (común al compartir configuraciones en un equipo), puedes canalizarla directamente:
echo '{
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "tu_clave"
}
}' | claude mcp add my-tools --json
O pasa un archivo:
claude mcp add my-tools --json < server-spec.json
Esto es equivalente a la forma posicional, pero te proporciona un único artefacto de configuración que puedes controlar versiones y compartir.
Listar y eliminar servidores
# Ver todos los servidores registrados
claude mcp list
# Eliminar un servidor
claude mcp remove my-tools
Ámbito: proyecto vs usuario
Por defecto, claude mcp add registra el servidor en tu configuración de usuario, haciéndolo disponible en cada sesión de Claude Code. Para registrarlo solo para el proyecto actual (almacenado en .claude/settings.json), agrega --scope project:
claude mcp add my-tools python /path/to/mcp_server.py --scope project
Los servidores con ámbito de proyecto son útiles cuando diferentes proyectos necesitan diferentes herramientas y deseas mantener las configuraciones aisladas.
claude mcp serve — exponer Claude Code como un servidor MCP
La dirección también funciona en sentido inverso. claude mcp serve inicia Claude Code como un servidor MCP, permitiendo que otro host MCP se conecte a él y use sus herramientas:
claude mcp serve
Esto es útil si deseas componer las capacidades de Claude Code en un pipeline de agente más grande donde un host diferente está orquestando las llamadas a herramientas.
Configuración de Servidores MCP en Claude Desktop
Claude Desktop almacena la configuración de los servidores MCP en un archivo JSON. La ubicación depende de tu sistema operativo:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Si el archivo no existe, créalo. La estructura tiene este aspecto:
{
"mcpServers": {
"my-tools": {
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "tu_clave_aqui"
}
}
}
}
Cada clave bajo mcpServers es el nombre del servidor que Claude usará para identificarlo. Puedes registrar tantos servidores como necesites — Claude Desktop los carga todos al inicio.
Después de editar el archivo, reinicia Claude Desktop para que los cambios surtan efecto. Verás un icono de martillo en el área de entrada del chat cuando las herramientas MCP se hayan cargado correctamente.
Agregar un servidor MCP remoto mediante SSE
Para servidores remotos que usan transporte SSE (Server-Sent Events) en lugar de stdio, la forma de configuración es ligeramente diferente:
{
"mcpServers": {
"remote-tools": {
"url": "https://tu-servidor-mcp.ejemplo.com/sse"
}
}
}
Algunos servidores remotos requieren autenticación. Pasa un token de portador en el campo de encabezados si el servidor lo espera:
{
"mcpServers": {
"remote-tools": {
"url": "https://tu-servidor-mcp.ejemplo.com/sse",
"headers": {
"Authorization": "Bearer tu_token_aqui"
}
}
}
}
Tipos de Transporte MCP: stdio vs SSE
Los servidores MCP se comunican con el host de Claude a través de uno de dos mecanismos de transporte:
stdio — El servidor se ejecuta como un subproceso en la misma máquina. El host inicia el proceso y lee/escribe mensajes JSON-RPC a través de la entrada/salida estándar. Este es el valor predeterminado para servidores locales y es el más simple de configurar.
SSE (Server-Sent Events) — El servidor se ejecuta de forma remota y expone un endpoint HTTP. El host se conecta a una URL y recibe las respuestas de la herramienta como un flujo. Esto funciona entre máquinas y es la opción adecuada para infraestructura de equipo compartida o servicios de herramientas alojados.
Para la mayoría de los desarrolladores individuales que están comenzando, stdio es más fácil — no requiere redes, y el proceso del servidor se gestiona por ti. SSE se vuelve valioso cuando deseas que un equipo comparta un único servidor MCP, o cuando la herramienta misma necesita ejecutarse en un entorno de red específico.
Cómo Razona Claude sobre las Herramientas MCP
Cuando comienza una sesión y los servidores MCP están registrados, Claude consulta a cada servidor por sus herramientas disponibles. Esto produce una lista de nombres de herramientas y descripciones de esquema JSON. Claude no llama a las herramientas de forma especulativa — solo invoca una herramienta cuando la conversación o tarea lo requiere, basándose en lo que dice la descripción de la herramienta que hace.
El flujo de llamada a herramientas funciona así:
- El usuario envía un mensaje o tarea.
- Claude evalúa si alguna herramienta registrada puede ayudar.
- Si es así, Claude construye una llamada a la herramienta con los argumentos apropiados.
- El host MCP envía la llamada al servidor correcto.
- El servidor ejecuta y devuelve un resultado.
- Claude incorpora el resultado en su razonamiento y continúa.
Este bucle puede ocurrir varias veces en un solo turno — Claude puede encadenar llamadas a herramientas, usar resultados de una herramienta para informar los argumentos de otra, y agregar resultados de múltiples servidores en la misma sesión.
La calidad de las descripciones de las herramientas es muy importante aquí. Las descripciones vagas llevan a invocaciones perdidas o incorrectas. Las descripciones precisas que incluyen qué hace la herramienta, qué significan sus argumentos y qué devuelve permiten que Claude enrute las llamadas con precisión sin adivinar.
Ejecución de Herramientas en un Entorno Aislado (Sandbox)
Cuando las herramientas MCP ejecutan código — scripts de Python, comandos de shell, operaciones de archivos — ejecutarlas en tu máquina local plantea preguntas sobre el aislamiento. Una herramienta con acceso al sistema de archivos, capacidad de crear procesos o llamadas de red tiene un alcance amplio si se comporta mal o es incitada a seguir una ruta inesperada.
Novita AI Agent Sandbox aborda esto proporcionando entornos en la nube aislados para la ejecución de herramientas. En lugar de ejecutar tu servidor MCP localmente, lo despliegas dentro de una instancia de sandbox. El sandbox tiene su propio sistema de archivos, alcance de red y límites de recursos. El agente puede escribir archivos, ejecutar código y llamar a APIs internas dentro de ese límite sin tocar la máquina host.
El servidor MCP que se ejecuta dentro del sandbox expone sus herramientas a través del transporte SSE, y Claude se conecta a él de forma remota — por lo que desde la perspectiva de Claude, la integración es idéntica. La diferencia está completamente en lo que la herramienta está ejecutando realmente.
Características clave del Novita Sandbox para despliegues MCP:
- Inicio rápido: las instancias se lanzan en menos de ~200ms, manteniendo baja la latencia de ida y vuelta de las herramientas
- Facturación por segundo: pagas solo por el tiempo de ejecución activo, no por la reserva inactiva
- Sistema de archivos aislado: cada instancia de sandbox tiene un espacio de trabajo separado, evitando la fuga de datos entre sesiones
- Política de red configurable: controla a qué servicios externos puede acceder la herramienta
Para una guía paso a paso sobre cómo construir un servidor MCP respaldado por un Novita Sandbox, consulta Build a Remote Code Execution MCP Server with Novita Sandbox and mcp-use Library.
Usando la API LLM de Novita para el Razonamiento sobre el Uso de Herramientas MCP
Si bien los propios modelos de Claude manejan el uso de herramientas de forma nativa, es posible que desees enrutar parte del razonamiento sobre el uso de herramientas MCP a través de un modelo diferente — por razones de costo, latencia o especialización. La API LLM de Novita proporciona un endpoint compatible con OpenAI con acceso a modelos que admiten llamadas a funciones e invocación estructurada de herramientas.
Esto encaja en las arquitecturas MCP de dos maneras:
1. Como el modelo de razonamiento detrás de un host MCP personalizado: Si estás construyendo tu propio host MCP (en lugar de usar Claude Code o Claude Desktop), puedes usar la API LLM de Novita para impulsar la capa del modelo. El host llama a la API de Novita con la lista de herramientas y la conversación; el modelo devuelve instrucciones de llamada a herramientas; el host las envía al servidor MCP.
import openai
client = openai.OpenAI(
base_url="https://api.novita.ai/v3/openai",
api_key="tu_clave_api_novita",
)
response = client.chat.completions.create(
model="meta-llama/llama-3.3-70b-instruct",
messages=[{"role": "user", "content": "Lista las herramientas disponibles y ejecuta una prueba rápida"}],
tools=[
{
"type": "function",
"function": {
"name": "list_models",
"description": "Lista todos los modelos disponibles de la API.",
"parameters": {"type": "object", "properties": {}},
}
}
],
tool_choice="auto",
)
2. Como el LLM dentro de una herramienta MCP: Una herramienta MCP puede usar la API LLM de Novita internamente — por ejemplo, una herramienta de resumen, una herramienta de clasificación o una herramienta que genera código. La herramienta acepta entradas del agente, llama a la API de Novita y devuelve el resultado. Esto mantiene los costos de inferencia del modelo separados de los costos del modelo del agente principal y te permite elegir el modelo adecuado para cada subtarea.
Para un ejemplo práctico de cómo construir un servidor MCP que llama a la API de Novita, consulta How to Build Your First MCP Server with Novita AI.
Problemas Comunes y Soluciones
El servidor no aparece en Claude Desktop
La causa más común es un error de sintaxis JSON en claude_desktop_config.json. Usa un validador JSON antes de guardar. Incluso una coma final impedirá que el archivo se cargue. Reinicia Claude Desktop después de cada edición.
El comando claude mcp add no se encuentra
Esto significa que Claude Code no está instalado o no está en tu PATH. Instala Claude Code mediante npm install -g @anthropic-ai/claude-code y verifica con claude --version.
Herramientas listadas pero nunca llamadas
Claude solo llama a una herramienta cuando cree que es relevante para la tarea actual. Si las descripciones de tus herramientas son demasiado vagas, Claude no las seleccionará. Agrega detalles: qué hace la herramienta, cuándo usarla, cómo son sus entradas y salidas.
El servidor se cierra inmediatamente después del inicio
Verifica que el comando del servidor sea correcto y que todas las variables de entorno requeridas estén configuradas. Ejecuta el comando directamente en una terminal para ver el mensaje de error real — Claude Code puede suprimir stderr del subproceso en algunas configuraciones.
Conexión SSE rechazada
Verifica que la URL del servidor sea accesible desde la máquina que ejecuta Claude, que el servidor esté realmente escuchando en el puerto esperado y que los encabezados de autenticación requeridos estén configurados correctamente.
Las llamadas a herramientas fallan con errores de validación
Los argumentos que Claude pasa deben coincidir con el esquema JSON que la herramienta declara. Revisa la definición de inputSchema de tu herramienta — si faltan campos obligatorios o los tipos no coinciden, el servidor rechazará la llamada. Claude construye los argumentos basándose en el esquema, por lo que un esquema incompleto lleva a llamadas incompletas.
Preguntas Frecuentes (FAQ)
¿Claude Code es compatible con MCP?
Sí. Claude Code tiene soporte nativo para MCP a través del subcomando claude mcp. Usa claude mcp add para registrar servidores, claude mcp list para ver qué está registrado y claude mcp remove para cancelar el registro. Ejecuta claude mcp --help para la referencia completa del comando.
¿Cómo agrego un servidor MCP a Claude Code?
Ejecuta claude mcp add <nombre> <comando> [args...] para un servidor stdio, o usa --json para pasar una especificación JSON. Para el registro con ámbito de proyecto, agrega --scope project. Después de agregarlo, inicia una nueva sesión de Claude Code — las herramientas estarán disponibles de inmediato.
¿Qué es claude mcp serve?
claude mcp serve ejecuta Claude Code como un servidor MCP, exponiendo sus capacidades a través del protocolo MCP. Otro host MCP puede entonces conectarse a Claude Code y usarlo como una fuente de herramientas. Esto es útil al construir sistemas multiagente donde Claude es un componente entre varios.
¿Puedo usar el mismo servidor MCP tanto en Claude Code como en Claude Desktop?
Sí. El servidor en sí no le importa qué host se conecte a él. Para servidores stdio, tanto Claude Code (a través de claude mcp add) como Claude Desktop (a través de claude_desktop_config.json) pueden lanzar el mismo comando. Para servidores SSE, cualquier host que pueda alcanzar la URL puede conectarse.
¿Cómo sabe Claude qué herramienta MCP llamar?
Al inicio de la sesión, Claude consulta a todos los servidores registrados por sus listas de herramientas. Cada herramienta tiene un nombre y una descripción. Al procesar una tarea, Claude selecciona las herramientas basándose en si sus descripciones coinciden con lo que se necesita. Las descripciones bien escritas con casos de uso claros conducen a una selección precisa de herramientas; las descripciones vagas conducen a llamadas perdidas o incorrectas.
¿Hay un límite en la cantidad de servidores MCP que puedo registrar?
La especificación MCP no impone un límite estricto, y tampoco lo hacen Claude Code o Claude Desktop. En la práctica, tener docenas de servidores con cientos de herramientas puede ralentizar el inicio de la sesión (el descubrimiento de herramientas se ejecuta al inicio) y puede agregar ruido a la selección de herramientas de Claude. Mantén el conjunto de herramientas centrado en lo que un proyecto o sesión determinada realmente necesita.
¿Cuál es la diferencia entre el transporte stdio y SSE?
Stdio ejecuta el servidor como un subproceso local; el host se comunica a través de stdin/stdout. SSE se conecta a un endpoint HTTP remoto y recibe respuestas como un flujo. Stdio es más simple para el desarrollo local; SSE es mejor para despliegues remotos, compartidos o de producción.
