Claude Code LSP: plugin, servidor y qué hacer si no funciona

A 2 de noviembre de 2026, con Claude Code 2.1.316, el LSP de Claude Code no se activa con ningún ajuste ni variable de entorno: son dos piezas que instalas tú. La primera es el servidor de lenguaje, un programa aparte como typescript-language-server o pyright-langserver. La segunda es el plugin de inteligencia de código del marketplace oficial, que no contiene el servidor: solo le dice a Claude Code qué programa arrancar y para qué extensiones de archivo. Para TypeScript y JavaScript son estos dos comandos:

# En tu terminal
npm install -g typescript-language-server typescript

# Dentro de Claude Code
/plugin install typescript-lsp@claude-plugins-official

En otros lenguajes cambia la pareja (pyright-lsp con pyright, gopls-lsp con gopls, rust-analyzer-lsp con rust-analyzer), y hay 13 plugins oficiales en total. Con todo instalado, Claude recibe dos cosas distintas: los diagnósticos del servidor, que llegan solos después de cada edición, y una herramienta LSP para ir a definiciones y referencias, que Claude usa solo cuando decide hacerlo. Para comprobarlo, pide a Claude que introduzca un error de tipo y lo corrija: si en la conversación aparece Found 1 new diagnostic issue in 1 file (ctrl+o to expand), el servidor está funcionando.

Hay dos excepciones que conviene conocer antes de empezar. Si /plugin install responde que el plugin no existe en claude-plugins-official, lo que falta es el propio marketplace, y se añade con /plugin marketplace add anthropics/claude-plugins-official. Y si no aparece ninguna línea de diagnósticos, Claude no te lo va a decir, porque cuando el servidor no arranca el modelo no recibe ningún error; tienes que mirarlo tú en /plugin, pestaña Errors, o con claude --debug. En sesiones en la nube los servidores de lenguaje no arrancan nunca.

Qué aporta LSP a Claude Code: diagnósticos y búsqueda por símbolo

LSP (Language Server Protocol) es el mismo protocolo con el que tu editor subraya errores y salta a la definición de una función. Según la documentación oficial de plugins de inteligencia de código, un plugin conecta Claude Code al servidor de lenguaje de un lenguaje concreto y le da dos cosas. Los diagnósticos llegan sin que nadie los pida: cada vez que Claude edita o escribe un archivo que maneja el servidor, recibe los errores de tipo, las importaciones que faltan y los errores de sintaxis que acaba de introducir, sin ejecutar el compilador. La herramienta LSP, en cambio, es de solo lectura y busca símbolos a través del servidor en lugar de buscar texto, pero es una herramienta más que Claude puede elegir o no.

La herramienta admite nueve operaciones: goToDefinition, findReferences, hover, documentSymbol, workspaceSymbol, goToImplementation, prepareCallHierarchy, incomingCalls y outgoingCalls. Cada llamada indica archivo, línea y columna (empezando en 1), y workspaceSymbol lleva además un texto de búsqueda. En un proyecto TypeScript de prueba de 3 archivos, con Claude Code 2.1.316 el 2 de noviembre de 2026, findReferences devolvió Found 5 references across 3 files y hover la firma completa, (alias) priceWithTax(amount: number, rate: number): number. Sobre un archivo sin plugin la respuesta fue No LSP server available for file type: .md.

La promesa de «pasar de buscar texto a entender código» se cumple sobre todo en la primera mitad. Los diagnósticos son lo único que una búsqueda con grep no puede darte; la navegación depende de que Claude decida usarla, y eso se trata al final, en la comparación con grep.

Instalar Claude Code LSP en tres pasos: servidor, plugin y prueba

El orden importa porque el plugin no incluye el servidor: si instalas solo el plugin, Claude Code intenta arrancar un programa que no existe y sigue trabajando como si nada. Desde una sesión de Claude Code en la terminal:

1. Instala el servidor de lenguaje con el comando de la tabla de la sección siguiente. Después confirma que está en el PATH del shell desde el que lanzas claude: which typescript-language-server en macOS o Linux, Get-Command typescript-language-server en PowerShell.
2. Abre Claude Code con claude y escribe /plugin install typescript-lsp@claude-plugins-official, cambiando typescript-lsp por el plugin de tu lenguaje. El comando abre la ficha del plugin en el panel /plugin para que elijas el alcance: Install for you (solo tú, en todos tus proyectos), Install for all collaborators on this repository (se guarda en .claude/settings.json del repositorio) o Install for you, in this repo only. Si el resumen final dice Run /reload-plugins to apply., ejecútalo o abre una sesión nueva; la pestaña Installed o claude plugin list muestran si quedó activo.
3. Pide a Claude que introduzca un error de tipo en un archivo de ese lenguaje y que después lo corrija. El servidor arranca con la primera edición de un archivo con una de sus extensiones; si todo va bien verás Found N new diagnostic issues in M files (ctrl+o to expand), y con Ctrl+O lees los errores concretos.

En la extensión de VS Code y en la aplicación de escritorio el paso 2 se hace desde su propio panel de plugins, no con el comando. Si después de instalar un binario que faltaba sigues sin diagnósticos, Claude Code vuelve a intentarlo en la siguiente edición de un archivo de ese lenguaje; si el binario quedó en una carpeta que tu shell no tiene en el PATH, abre una sesión nueva desde un shell donde sí esté. Si todavía no tienes Claude Code, empieza por Cómo instalar Claude Code en Windows, Mac o Linux y actualizarlo.

Qué plugin y qué servidor necesita cada lenguaje

El marketplace oficial claude-plugins-official tiene 13 plugins de inteligencia de código a 2 de noviembre de 2026. Anthropic mantiene todos menos liquid-lsp, que mantiene Shopify. El nombre del plugin no siempre coincide con el del servidor (el de Python se llama pyright-lsp, pero el programa que arranca es pyright-langserver), así que lo que tiene que estar en el PATH es lo de la tercera columna.

Los comandos salen del README de cada plugin en el marketplace oficial, en su versión del 30 de octubre de 2026. La configuración de jdtls-lsp y kotlin-lsp da a esos servidores hasta 120 segundos para arrancar, así que en Java y Kotlin las primeras ediciones pueden quedarse sin diagnósticos mientras el servidor termina de cargar.

«Plugin "typescript-lsp" not found in marketplace»: falta el marketplace oficial

Este error no significa que el plugin no exista, sino que tu instalación de Claude Code no tiene registrado el marketplace oficial. Según la página de solución de problemas de plugins de Claude Code, Claude Code lo registra normalmente la primera vez que abres una sesión interactiva en la terminal; no lo hace si hasta ahora solo usaste la extensión de VS Code, si una política de tu organización bloquea la fuente, si está definida CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL o si un intento anterior falló y está esperando para reintentar. Además, los comandos claude plugin del shell no lo registran nunca. La solución es añadirlo a mano y repetir la instalación:

/plugin marketplace add anthropics/claude-plugins-official
/plugin install typescript-lsp@claude-plugins-official

El 2 de noviembre de 2026, con Claude Code 2.1.316 en macOS y una carpeta de configuración nueva (CLAUDE_CONFIG_DIR aislada, sin ninguna sesión interactiva previa), claude plugin install typescript-lsp@claude-plugins-official falló con este mensaje:

✘ Failed to install plugin "typescript-lsp@claude-plugins-official": Plugin "typescript-lsp" not found in marketplace "claude-plugins-official". Your local copy may be out of date — try claude plugin marketplace update claude-plugins-official.

La sugerencia del propio error no sirve: claude plugin marketplace update claude-plugins-official respondió Marketplace 'claude-plugins-official' not found. Available marketplaces: anthropic-plugin-directory, porque no hay copia local que actualizar. Con claude plugin marketplace add anthropics/claude-plugins-official el resultado fue Successfully added marketplace: claude-plugins-official, y la instalación posterior terminó con Successfully installed plugin: typescript-lsp@claude-plugins-official (scope: user). La documentación cita el mismo problema con otro texto, Marketplace "claude-plugins-official" not found; las dos variantes se arreglan igual.

Cómo saber que funciona: lo que recibe Claude después de una edición

La señal fiable es la línea de diagnósticos en la conversación, pero no llega pegada a la edición, y eso explica buena parte de los «no hace nada». Para ver qué recibe exactamente el modelo, el 2 de noviembre de 2026 se conectó Claude Code 2.1.316 (macOS, configuración aislada) a un endpoint mock local en vez de a un modelo real. El mock respondía con llamadas a herramientas preparadas de antemano y guardaba cada petición que enviaba Claude Code, de modo que lo que sigue es lo que un modelo habría leído, palabra por palabra. El servidor era typescript-language-server 6.0.2 con TypeScript 5.9.3, sobre el mismo proyecto de 3 archivos.

Cuando Claude escribió un .ts con un error, el servidor respondió a la inicialización en 69 ms y publicó el diagnóstico unos 0,58 segundos después de abrir el archivo. Aun así, el error no apareció en el resultado de la herramienta de escritura: llegó en el turno siguiente, como un bloque de sistema aparte.

<new-diagnostics>The following new diagnostic issues were detected:

checkout.ts:
  ✘ [Line 3:43] Argument of type 'string' is not assignable to parameter of type 'number'. [2345] (typescript)</new-diagnostics>

Esto tiene dos consecuencias. Si Claude da la tarea por terminada justo después de la edición, puede no ver el error; Scott Spence lo describe en su informe del 10 de octubre de 2026, Revisiting LSP in Claude Code, donde en dos sesiones cortas el error de tipo nunca se reportó y en otra más larga llegó unos 30 segundos después. Y cuando Claude corrige el error no recibe ningún aviso de «resuelto»: el servidor publica cero diagnósticos y Claude Code no envía nada. Ese silencio no demuestra que el archivo esté bien, porque Scott también vio que se pierden diagnósticos mientras un servidor recién arrancado carga el proyecto y que los cambios hechos desde el shell (un git checkout, un formateador, un script) no se reportan. Su regla es que la ausencia de diagnósticos justo después de una edición no significa que la edición esté limpia, así que pide la comprobación de tipos antes de dar algo por terminado.

En la terminal pasa algo parecido. La documentación dice que la línea Found N new diagnostic issues sale bajo la edición que introdujo el error, pero en la misma prueba apareció una fila más abajo, bajo la siguiente herramienta ("Ran 1 shell command"), porque la entrega es asíncrona. Si no la ves debajo de la edición, mira la fila siguiente antes de concluir que no funciona. La herramienta LSP tampoco está en la lista de herramientas desde el principio: después de la primera escritura o lectura de un .ts, Claude Code le avisa al modelo de que LSP está disponible como herramienta de carga diferida, y su definición solo se envía cuando el modelo la pide con ToolSearch.

Lo instalé y no hace nada: síntoma, causa y solución

Cuando el servidor no arranca, Claude no se entera. En las pruebas del 2 de noviembre de 2026 con la versión 2.1.316, tanto con el binario fuera del PATH como con el paquete typescript ausente del proyecto, el modelo siguió viendo la herramienta LSP como disponible y no recibió ni diagnósticos ni texto de error. Por eso la causa tienes que buscarla tú: en /plugin, pestaña Errors, o arrancando con claude --debug, que registra una línea LSP server ... failed to start con el motivo.

Si una configuración rota impide trabajar, CLAUDE_CODE_SAFE_MODE=1 o claude --safe-mode arrancan la sesión sin servidores LSP, lo que sirve para separar un problema del plugin de uno de Claude Code.

El primer findReferences devuelve solo la definición: desactiva el syntax server

Si la primera búsqueda de referencias de una sesión devuelve Found 1 reference y apunta a la propia definición, no es que la función no se use. Claude Code pregunta antes de que el proyecto termine de cargarse, y typescript-language-server responde desde su servidor ligero de sintaxis (syntax server), que solo conoce el archivo abierto. En el informe de Scott Spence del 10 de octubre de 2026, la primera llamada de una sesión nueva falló en 18 de las primeras 19 sesiones y en las 13 que cronometró después, con resultados correctos al repetir; también cuenta que otros usuarios ven el mismo patrón «una referencia, luego todas» con servidores de Python, y que hay una incidencia abierta en el repositorio de Claude Code.

El 2 de noviembre de 2026, con Claude Code 2.1.316, typescript-language-server 6.0.2 y el proyecto de 3 archivos (respuesta correcta: 5 referencias en 3 archivos), el primer findReferences de la sesión devolvió Found 1 reference: src/price.ts:1:17 en las 3 sesiones con el plugin oficial. Las tres llamadas seguidas de cada sesión dieron 1, 5, 5; 1, 1, 1 y 1, 1, 5. Con la opción useSyntaxServer: "never" en una copia local del plugin, cargada con --plugin-dir y con el oficial desactivado, las 2 sesiones dieron 5, 5, 5. Esta es la configuración completa del servidor con la opción añadida en initializationOptions:

{
  "typescript": {
    "command": "typescript-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": { ".ts": "typescript", ".tsx": "typescriptreact", ".js": "javascript", ".jsx": "javascriptreact", ".mts": "typescript", ".cts": "typescript", ".mjs": "javascript", ".cjs": "javascript" },
    "initializationOptions": { "tsserver": { "useSyntaxServer": "never" } }
  }
}

Hay dos formas de aplicarla. La rápida es editar la entrada typescript dentro de lspServers en ~/.claude/plugins/marketplaces/claude-plugins-official/.claude-plugin/marketplace.json, que es donde vive la configuración del plugin oficial (la carpeta del plugin solo contiene README y licencia); el inconveniente es que una actualización del marketplace puede sobrescribir el archivo. La estable es crear un plugin propio: una carpeta con .claude-plugin/plugin.json (por ejemplo { "name": "typescript-lsp-nosyntax", "version": "0.1.0" }) y un .lsp.json con el bloque de arriba, desactivar el oficial con /plugin disable typescript-lsp@claude-plugins-official y lanzar claude --plugin-dir ./typescript-lsp-nosyntax. Así se hizo en la prueba descrita. Scott publica su propia copia en un marketplace personal; antes de instalar plugins de terceros, revisa qué pueden hacer con Claude Code mods: qué son, cómo usarlos y a qué pueden acceder.

El arreglo tiene un precio pequeño: la primera llamada espera a que el proyecto cargue, unos 2 segundos en el repositorio de Scott, y en un proyecto grande la espera será mayor. A cambio, en su proyecto la memoria bajó de unos 935 MB en 4 procesos a unos 725 MB en 3. La opción es propia de typescript-language-server; para los servidores de Python el informe no da un arreglo equivalente, así que ahí toca repetir la llamada.

¿Sigue haciendo falta ENABLE_LSP_TOOL? No: en 2.1.316 no cambia nada

No. Los tutoriales de principios de 2026 pedían añadir "env": {"ENABLE_LSP_TOOL": "1"} a settings.json, y alguno lo sigue diciendo, como el artículo de Karan Bansal sobre LSP en Claude Code del 28 de febrero de 2026, que lo presenta como un truco de la comunidad sin documentar. Esa variable no aparece en la referencia oficial de variables de entorno, y Scott Spence cuenta que la quitó en la versión 2.1.296 y LSP siguió cargando.

La prueba del 2 de noviembre de 2026 con la 2.1.316 fue en los dos sentidos. Con el plugin instalado y ENABLE_LSP_TOOL=0, la herramienta LSP siguió disponible y los diagnósticos siguieron llegando; con el plugin desactivado y ENABLE_LSP_TOOL=1, no hubo herramienta y el registro de depuración indicó Total LSP servers loaded: 0. Lo que enciende LSP es el plugin, así que puedes borrar la variable de tu settings.json sin perder nada.

Diálogo «LSP plugin recommendation»: qué opción elegir

Si ves el diálogo LSP plugin recommendation, Claude Code ha detectado que tienes el servidor de un lenguaje instalado pero no su plugin, y te ofrece instalarlo. Aparece después de que Claude edita un archivo, cuando alguno de tus marketplaces (o el oficial) tiene un plugin para esa extensión y su binario está en tu PATH; sale como mucho una vez por sesión, da prioridad al marketplace oficial y nunca aparece en sesiones en la nube. Si trabajas a diario en ese lenguaje, Yes, install es la opción razonable. El 2 de noviembre de 2026 se reprodujo con la versión 2.1.316: con typescript-language-server en el PATH, el plugin desinstalado y Claude escribiendo un .ts, el diálogo ofreció typescript-lsp («Triggered by: .ts files»); con el plugin instalado pero desactivado no apareció.

Ignorar el diálogo también cuenta. Si no respondes en 30 segundos se toma como ignorado, y tras cinco diálogos ignorados las recomendaciones se apagan como si hubieras elegido la cuarta opción. Para recuperarlas, borra lspRecommendationDisabled y lspRecommendationIgnoredCount de ~/.claude.json.

Añadir un lenguaje sin plugin oficial con .lsp.json

Si tu lenguaje no está en la tabla, puedes conectar cualquier servidor de lenguaje con un plugin propio que solo contenga un .lsp.json. Este ejemplo usa yaml-language-server para archivos .yaml y .yml:

1. Instala el servidor de lenguaje y comprueba con which yaml-language-server que está en el PATH.

2. Crea una carpeta yaml-lsp-local con estos dos archivos. El primero es .claude-plugin/plugin.json:

   jsonCopiar

   { "name": "yaml-lsp-local", "version": "0.1.0", "description": "yaml-language-server for .yaml/.yml" }

   El segundo, en la raíz de la carpeta, es .lsp.json:

   jsonCopiar

   {
     "yaml": {
       "command": "yaml-language-server",
       "args": ["--stdio"],
       "extensionToLanguage": { ".yaml": "yaml", ".yml": "yaml" }
     }
   }

3. Arranca Claude Code con el plugin y el registro de depuración: claude --debug --plugin-dir ./yaml-lsp-local. Si la configuración es válida, el registro muestra Loaded 1 LSP server(s) from plugin: yaml-lsp-local.

4. Cuando funcione, sigue cargándolo con --plugin-dir o publícalo en un marketplace para instalarlo con /plugin install.

La trampa está en el paso 3: no te fíes de claude plugin validate. En la prueba del 2 de noviembre de 2026 con la 2.1.316, ese comando respondió «Validation passed with warnings» tanto para el archivo correcto como para tres versiones rotas: una con una clave desconocida (extensions), otra con espacios en command y otra con una extensión sin punto. Los avisos solo se referían a que faltaban README, licencia o icono. El error real aparece al cargar: con la clave desconocida, el registro de depuración mostró LSP config validation failed for .lsp.json in plugin yaml-lsp-local con unrecognized_keys y el servidor no se cargó.

Según la referencia de plugins de Claude Code, las reglas del archivo son estrictas. Solo son obligatorios command, que no puede llevar espacios salvo que empiece por / (los argumentos van en args), y extensionToLanguage, cuyas claves empiezan por punto; cualquier clave que no esté en la lista hace fallar la validación. Los campos opcionales que más se usan son args, env, initializationOptions, settings, startupTimeout, requestTimeout (60.000 ms por defecto, desde la 2.1.288), restartOnCrash, maxRestarts y diagnostics, que permite apagar los diagnósticos automáticos y dejar solo la navegación.

Memoria y desactivar el plugin LSP

Desactívalo cuando el servidor pese más de lo que aporta. La documentación oficial señala que rust-analyzer y pyright indexan el proyecto entero, y para esos casos recomienda /plugin disable seguido del nombre del plugin y volver a la búsqueda integrada de Claude. Como referencia, Scott Spence midió unos 935 MB en 4 procesos para typescript-language-server en su proyecto SvelteKit. En Linux y WSL, si usas CLAUDE_CODE_TOOL_MEMORY_LIMIT, los servidores de lenguaje pueden contar contra ese límite; CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE=lsp los deja fuera.

Hacerlo a mitad de sesión tiene un coste, y lo mismo vale al activar o reactivar un plugin. Un /reload-plugins normal que añade o quita la herramienta LSP no recarga nada: Claude Code muestra This reload removes the LSP tool (o This reload adds the LSP tool), avisa de que el siguiente mensaje releerá toda la conversación en vez de usar la caché y te pide /reload-plugins --force para aplicarlo. Empezar una sesión nueva evita esa relectura. Por qué eso encarece un turno lo explica Claude Code cache miss y coste de tokens: por que un turn sale caro.

¿Necesitas el plugin LSP si usas Claude Code en VS Code?

Sí, si quieres los diagnósticos automáticos y la herramienta LSP. Según la documentación de Claude Code para VS Code, la extensión le da a Claude otra cosa: la CLI integrada con VS Code expone mcp__ide__getDiagnostics, y en el panel de chat (desde la 2.1.285) Claude lee el panel Problemas a través del servidor integrado claude-vscode. Son los errores del servidor de lenguaje de tu editor, leídos cuando Claude los pide, no los diagnósticos que llegan solos tras cada edición ni la navegación por símbolos. Para tener esas dos cosas también en VS Code hay que instalar el servidor y el plugin, desde el panel de plugins de la extensión.

LSP frente a grep: ¿usará Claude la herramienta?

Depende de lo que pidas y de las reglas que le des. En el informe de Scott Spence del 10 de octubre de 2026, con una regla explícita en CLAUDE.md Claude usó LSP en 12 de 12 preguntas sobre símbolos; sin la regla, más o menos en la mitad, y nunca en la refactorización. Su historial real fue más pobre: 32 llamadas a LSP en 15 de unas 650 sesiones.

Lo más útil de ese informe es su comparación posterior. En 54 sesiones sobre su repositorio, grep sin LSP acertó todas las preguntas y fue lo más rápido para encontrar dónde se usa una función; con solo LSP, Claude no encontró un vi.mock de un test que se habría roto, porque para TypeScript eso no es una referencia, ni pudo revisar los archivos .svelte. Donde LSP sí ganó fue en tipos: hover da el tipo exacto en una llamada. Scott acabó escribiendo en su CLAUDE.md que use grep para buscar usos, hover para tipos, que no tome un findReferences como lista completa y que ejecute la comprobación de tipos antes de terminar. Su conclusión coincide con lo que se ve en las pruebas de arriba: la razón para instalar LSP son los diagnósticos.

Si quieres que Claude prefiera LSP en ciertos casos, una regla en CLAUDE.md es el camino directo; para decidir si te conviene más una regla, un hook o una skill, mira Claude Code: hooks, comandos de barra y skills, ¿cuál usar?. LSP tampoco sustituye a un servidor MCP: uno da a Claude el análisis de tu propio código y el otro lo conecta con herramientas y servicios externos, como explica Los mejores MCP para Claude Code: cuál instalar primero.

Preguntas frecuentes sobre Claude Code LSP

¿Desde qué versión de Claude Code existe la herramienta LSP? Según el registro de cambios oficial de Claude Code, la herramienta llegó en la versión 2.0.74, el 19 de diciembre de 2025. La 2.1.74 (12 de marzo de 2026) arregló LSP en Windows, que fallaba por URI de archivo mal formadas, y la 2.1.288 (2 de octubre de 2026) añadió un tiempo límite de 60 segundos por petición. Si tu versión es anterior a esas, actualiza antes de buscar otras causas.

¿La herramienta LSP de Claude Code pide permiso? No. Según la referencia de herramientas de Claude Code, LSP se usa sin pedir confirmación, pero las reglas de permisos Read(...) que restringen rutas también se aplican a ella, así que no podrá consultar archivos que tengas bloqueados para lectura.

¿Funciona LSP con claude -p en scripts? Sí. Scott Spence hizo sus pruebas de octubre de 2026 con sesiones sin interfaz lanzadas con claude -p, y la herramienta LSP respondió igual que en las interactivas. La excepción es --bare, que según la documentación omite los servidores LSP, así que si tus scripts usan ese modo no tendrán diagnósticos.