OpenCode LSP Guide: What It Does, How to Enable It, and Fix Disabled Servers

LSP stands for Language Server Protocol. A language server runs alongside the project and exposes structured information about files: diagnostics, symbols, definitions, references, hover details, and other capabilities supported by that implementation. OpenCode can use that information as part of a coding session instead of treating every file as unstructured text.

The practical benefit is context quality. If a TypeScript server understands that a symbol is imported from another module, an agent can reason about a rename or type error with stronger evidence. That does not make every answer correct: the server may be missing, the project may not load, or the language package may have its own configuration requirements. LSP improves the information available to the workflow; it does not replace review, tests, or a Git diff.

An LSP entry needs an executable command and a clear relationship to file extensions. The command starts the server, usually over standard input and output, while the extension list tells OpenCode which files should use that server. The exact executable, arguments, installation method, and project requirements come from the server documentation; do not guess a package name from a search result.

Start with one language in a small repository. Open a file with the expected extension, confirm the server process can start outside the agent when practical, and then ask for a read-only summary or diagnostic check. If the file extension does not match, a valid server can appear broken because OpenCode has no reason to attach it to the file.

Put shared LSP decisions in a reviewed project configuration when the whole repository needs them. Keep personal experiments in global configuration until the command, extension mapping, and expected project root are understood. The existing OpenCode JSONC guide explains configuration scope and schema validation; use that page when the question is precedence or secret-free config ownership rather than LSP behavior.

A minimal entry is easier to debug than a large catalog. Give the server a descriptive key, keep the command array explicit, and list only the extensions that the server actually supports. If the server needs initialization options, add them after the basic process works. A valid JSON document can still fail at runtime when the executable, workspace, or language package is wrong.

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "typescript": {
      "command": ["typescript-language-server", "--stdio"],
      "extensions": [".ts", ".tsx"]
    }
  }
}

The current official docs state that if lsp is omitted, all LSP servers are disabled. To disable every server after another configuration enabled them, set lsp to false. To disable one named server, set its disabled value to true. These are useful controls when a server is slow, noisy, incompatible with a repository, or not allowed in a particular environment.

Custom servers are useful for languages or file types that are not covered by the built-in configuration. Define the command and extensions first, then add initialization options only when the server documents them. Keep a copy of the last known-good configuration and test one change at a time so a broken custom entry does not look like a model or MCP failure.

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": false
}

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "custom-lsp": {
      "command": ["custom-lsp-server", "--stdio"],
      "extensions": [".custom"],
      "initialization": { "preferences": { "mode": "strict" } }
    }
  }
}

Do not begin by asking the agent to rewrite a large module. Use a repository with a clean Git status, open one known file, and make the first request read-only. Ask OpenCode to identify a symbol, explain a diagnostic, or locate a definition. The result should be specific enough to compare with the editor, compiler, or language server output you already trust.

Once the read-only path works, make one reversible edit and inspect the diff. Record the operating system, server command, extension mapping, project root, and the exact test prompt. That small note turns a one-off success into a reproducible setup and makes future failures easier to classify.

1. CleanStart from a repository whose branch and working tree are known.
2. MatchOpen a file with an extension listed in the LSP entry.
3. ReadAsk for a symbol, definition, reference, or diagnostic explanation.
4. EditMake one small reversible change and inspect the diff.
5. RecordSave the command, model, server, and rollback note.

When OpenCode reports that LSP servers are disabled, check configuration precedence before reinstalling anything. A higher-precedence file may set lsp to false, the project may omit the server name, or a per-server disabled flag may be active. Compare the resolved project path with the directory where the config file actually lives.

If the server is enabled but diagnostics are empty, check the command and extension mapping next. Run the server in the same shell when possible, verify its runtime and PATH, and inspect whether the project needs a lockfile, compiler configuration, or workspace root. Slow results often come from a server indexing a large repository rather than from the OpenCode model.

Keep permission changes narrow. LSP needs a process and project context; it does not automatically justify broad shell access, a wider MCP catalog, or an auto-approval mode. The existing permissions guide covers ask, allow, and deny decisions, while the MCP guide covers external tool servers. Link those guides when the failure crosses layers.

LSP is about language intelligence inside the repository. MCP connects external tools or data services. A formatter changes style, and a test runner provides executable evidence. VS Code can host its own language integrations, but the fact that an editor shows diagnostics does not prove that an OpenCode session is using the same server or project root.

Use the matching guide when the symptom belongs elsewhere: the OpenCode MCP setup covers local and remote tool servers, the VS Code guide covers editor context and terminal integration, and the permissions guide covers approval boundaries. Keeping these page intents separate also keeps opencode lsp focused on language-server configuration rather than becoming a generic setup page.