Toeverything·Publicado 20 ago 2026 · Actualizado 21 ago 2026
Cómo agregar servidores MCP a Claude Code: guía y solución
Productividad
Lo esencial en 30 segundos
Claude Code habla MCP de fábrica: para un servidor remoto basta un comando claude mcp add y unos minutos; si el servicio usa OAuth, /mcp completa el inicio de sesión en el navegador.
La configuración vive en uno de tres alcances (local, project y user). Lo que se comparte con el equipo va en project; las credenciales se quedan en el alcance personal.
Claude Desktop tiene dos caminos: Conectores para servidores remotos y archivo de configuración para los locales. Sus ajustes son independientes de los de Claude Code.
¿El servidor no aparece? Dentro de la sesión, el comando /mcp muestra el estado de la conexión: empieza siempre por ahí.
Esta guía cubre el comando claude mcp add y la lógica de los alcances, la configuración en Claude Desktop, el recorrido completo usando un workspace de AFFiNE como ejemplo y la lista de verificación para cuando nada aparece. Si el concepto todavía no está claro, empieza por qué es un servidor MCP.
Agregar servidores MCP a Claude Code
Para un servidor remoto (HTTP), el caso más común con servicios alojados:
Para un servidor local (stdio), que Claude Code ejecuta en tu máquina:
claude mcp add <nombre> -- <comando-que-inicia-el-servidor>
Para servicios que se autentican con OAuth en lugar de un token fijo, como Notion o Sentry, el comando es el mismo pero sin --header: el servidor queda en «Needs authentication» hasta que ejecutas /mcp dentro de la sesión, eliges Authenticate e inicias sesión en el navegador. Claude Code guarda el token y lo renueva automáticamente; claude mcp login ejecuta el mismo flujo desde la terminal.
El mantenimiento cabe en tres subcomandos: claude mcp list para ver lo configurado (con el estado de conexión de cada servidor), claude mcp get para el detalle y claude mcp remove para borrar. Si un producto entrega el JSON listo, claude mcp add-json '' lo acepta tal cual. Durante la sesión, el comando /mcp muestra el estado de la conexión y las herramientas disponibles: el primer lugar donde mirar cuando algo falla. La referencia completa de banderas y transportes está en la documentación oficial de MCP en Claude Code.
Alcances: local, project y user
Dónde se guarda la configuración define quién la ve:
local (predeterminado): este proyecto, esta máquina, solo tú. Para experimentos y credenciales personales.
project: se escribe en un archivo .mcp.json en la raíz del repositorio, versionado y compartido con todo el equipo. Es el lugar de los servidores estándar del equipo, como la base de conocimiento; cada persona aprueba el servidor en el primer uso.
user (--scope user): vale para ti en todos los proyectos de la máquina. Para servidores personales de uso constante. Los dos alcances personales, local y user, viven en ~/.claude.json, fuera del repositorio.
La regla práctica: las credenciales se quedan en el lado personal; lo que se comparte vía project es la definición del servidor. Para eso, .mcp.json admite la expansión ${VAR}: la entrada versionada declara Authorization: Bearer ${AFFINE_TOKEN} y cada persona define esa variable en su máquina, así el archivo del repositorio nunca contiene un token. Y si el mismo nombre existe en más de un alcance, gana el más cercano: local sobre project, y project sobre user.
Agregar en Claude Desktop
Servidor remoto: Configuración → Conectores → agregar conector personalizado, pegar la URL y autorizar. Es el camino sin terminal; para servidores alojados como el de AFFiNE o el de Notion, es todo lo que hace falta.
Servidor local: edita claude_desktop_config.json (Configuración → Desarrollador → editar configuración), agrega el servidor en mcpServers y reinicia la aplicación.
Los mismos servidores funcionan en Claude Code y en Claude Desktop, pero cada aplicación guarda su propia configuración: configúrala una vez en cada una que uses. Un atajo para no repetir el trabajo: claude mcp add-from-claude-desktop importa a Claude Code, con un diálogo interactivo, los servidores que ya tenías en Desktop (funciona en macOS y WSL).
De principio a fin: conectar tu base de conocimiento
El ciclo completo con el servidor MCP integrado de AFFiNE, que vuelve consultables los documentos y pizarras del workspace desde cualquier cliente MCP:
Crea la credencial. En AFFiNE: Configuración → Integrations → MCP Server → Create credential. Ponle el nombre del cliente («Claude Code»; una credencial por cliente hace que revocar sea trivial), deja el acceso predeterminado de solo lectura y define la caducidad.
Copia la configuración. El token aparece una sola vez, junto al botón Copy JSON, que genera la configuración completa: URL del endpoint y encabezado de autenticación incluidos. El endpoint tiene la forma https://app.affine.pro/api/workspaces//mcp; en instancias autoalojadas va la dirección de tu servidor.
Úsalo. Abre una sesión y haz una pregunta que solo tus notas pueden responder: «busca el diseño de reintentos de pago y resume los puntos abiertos». Claude Code llama a la herramienta de búsqueda (palabra clave + semántica, pizarras incluidas), lee el documento dentro de tus permisos —le llega como Markdown limpio— y responde con tu contenido real.
Sin costo adicional: funciona en AFFiNE Cloud y en instancias autoalojadas con las funciones de IA activadas.
El transporte determina dónde se ejecuta el servidor; los permisos de la credencial determinan a qué herramientas y datos puede acceder el cliente.
La misma configuración en Cursor y ChatGPT
Cursor lee ~/.cursor/mcp.json (o .cursor/mcp.json por proyecto). La salida de Copy JSON de AFFiNE coincide con el formato de Cursor tal cual: pegar, reiniciar, listo.
ChatGPT se conecta a servidores MCP remotos mediante conectores; los servidores personalizados requieren el modo de desarrollador (Configuración → Conectores → Avanzado). El mismo endpoint y el mismo encabezado pasan sin cambios. Un servidor, todos los asistentes: esa es la gracia de MCP.
Solución de problemas: el servidor no aparece
Recorre la lista en orden; la gran mayoría de los casos termina aquí:
Primero /mcp. Ahí se ve si el servidor conectó, falló la autenticación o ni siquiera arrancó. Leer el error mostrado es más rápido que adivinar.
Transporte equivocado. Un servidor alojado exige --transport http; sin la bandera, Claude Code trata la URL como comando local. Quítalo y agrégalo de nuevo con la bandera.
Encabezado mal escrito. El formato es Authorization: Bearer : un Bearer faltante o un espacio de más se convierte en un 401 sin pistas. No lo escribas a mano; pégalo desde Copy JSON.
Credencial caducada o revocada. Un token con fecha de caducidad algún día caduca. Emite una credencial nueva y regístrala otra vez.
Alcance confundido. Un servidor agregado con alcance local no existe en otros proyectos. Ejecuta claude mcp list en la carpeta donde esperabas verlo y saldrás de dudas.
Pendiente de aprobación o de inicio de sesión. Un servidor compartido por .mcp.json aparece como «Pending approval» hasta que lo apruebas en una sesión interactiva; si rechazaste uno por error, claude mcp reset-project-choices restablece la decisión. Y un servidor OAuth queda en «Needs authentication» hasta completar el flujo desde /mcp.
Falta una dependencia del servidor local. Un servidor stdio ejecuta un comando; sin el runtime instalado, muere al arrancar. Ejecuta ese comando a mano una vez y lee el error real. Dos matices: la primera ejecución con npx puede tardar mientras descarga el paquete (reintenta claude mcp list un momento después), y si olvidas el separador --, Claude Code lee las banderas del servidor como si fueran propias.
Conecta pero no se usa. Las primeras veces, menciona la fuente en tu petición («busca en mi workspace de AFFiNE...»). Establecido el patrón, Claude elige la herramienta correcta por sí solo.
Prácticas de seguridad que conviene mantener
Solo lectura hasta que escribir sea necesario. Una conexión de base de conocimiento rara vez necesita escribir; las credenciales de AFFiNE se crean de solo lectura y la escritura está en despliegue progresivo.
Una credencial por cliente. Revocar la de la laptop no debería afectar la del equipo de escritorio. Con caducidad definida, la rotación es un trámite de calendario.
Aprobación de herramientas con criterio. Claude pregunta antes de usar una herramienta nueva, y los servidores compartidos por project se aprueban en el primer uso. No lo desactives para nada que modifique datos. La lista completa está en nuestra guía de seguridad MCP (en inglés).
Preguntas frecuentes
¿Qué comando agrega un servidor MCP a Claude Code?
El comando claude mcp add: para servidores alojados, con --transport http, la URL y el encabezado de autenticación; para locales, con el comando de arranque. Verifica con claude mcp list y, dentro de la sesión, /mcp muestra el estado al momento.
¿Claude Desktop admite servidores MCP?
Sí. Los servidores remotos entran por Configuración → Conectores como conector personalizado; los locales van en claude_desktop_config.json, bajo mcpServers, con reinicio. Solo recuerda que su configuración es independiente de la de Claude Code.
¿En qué se diferencian los alcances local, project y user?
local vale para ti en un solo proyecto; project escribe un .mcp.json compartido en el repositorio para todo el equipo; user vale para ti en todos los proyectos de la máquina. Las credenciales quedan en el lado personal: por project se comparte solo la definición del servidor y, con la expansión ${VAR} de .mcp.json, cada persona aporta su token mediante una variable de entorno.
¿Claude Code puede conectarse a servidores MCP remotos?
Sí. Los servidores remotos por Streamable HTTP tienen soporte oficial con --transport http y encabezado de autenticación. Los endpoints alojados, como el del workspace de AFFiNE, se conectan sin ningún proceso local que mantener.
¿Cómo me autentico con un servidor MCP que usa OAuth?
Agrega el servidor sin encabezado (claude mcp add --transport http ) y ejecuta /mcp dentro de la sesión: al elegir Authenticate se abre el navegador para iniciar sesión, y Claude Code guarda y renueva el token automáticamente. Desde la terminal, claude mcp login ejecuta el mismo flujo, y la opción «Clear authentication» del menú /mcp revoca el acceso.
¿Por qué mi servidor no aparece en la lista?
Revisa el estado con /mcp y luego los sospechosos de siempre: falta --transport http en un servidor remoto, encabezado Authorization mal formado, credencial caducada o alcance confundido (local solo existe en el proyecto donde se agregó). Esos cuatro explican casi todo.
¿Usar MCP en Claude cuesta algo?
El soporte de MCP viene incluido sin costo extra en Claude Code y Claude Desktop, y el protocolo es de código abierto. Las condiciones varían por servidor; el integrado de AFFiNE, por ejemplo, es gratuito en Cloud y en instancias autoalojadas con IA activada.
En resumen
Conectado el primero, el segundo sale solo: el procedimiento es el mismo para cualquier servidor. Empieza por el lugar donde pasas el día buscando respuestas: tu propio workspace.