LSP Tool

Connect to Language Server Protocol servers for code intelligence.

Overview

The LSP tool connects your agent to any Language Server Protocol (LSP) server, providing comprehensive code intelligence capabilities like go-to-definition, find references, diagnostics, and more.

Note

What is LSP?

The Language Server Protocol is a standard for providing language features like autocomplete, go-to-definition, and diagnostics. Most programming languages have LSP servers available.

Available Tools

The LSP toolset provides these tools to the agent:

Configuration

agents:
  developer:
    model: anthropic/claude-sonnet-4-5
    description: Code developer with LSP support
    instruction: You are a software developer.
    toolsets:
      - type: lsp
        command: gopls
        args: []
        file_types: [".go"]
      - type: filesystem
      - type: shell

Properties

Common LSP Servers

Here are configurations for popular languages:

Go (gopls)

toolsets:
  - type: lsp
    command: gopls
    version: "golang/tools@v0.21.0" # optional: auto-install if not in PATH
    file_types: [".go"]

If your Go module lives in a subdirectory (e.g. a monorepo where go.mod is under ./backend), set working_dir so gopls is started from the module root:

toolsets:
  - type: lsp
    command: gopls
    file_types: [".go"]
    working_dir: ./backend # gopls must be started from the module root

TypeScript/JavaScript (typescript-language-server)

toolsets:
  - type: lsp
    command: typescript-language-server
    args: ["--stdio"]
    file_types: [".ts", ".tsx", ".js", ".jsx"]

Python (pylsp)

toolsets:
  - type: lsp
    command: pylsp
    file_types: [".py"]

Rust (rust-analyzer)

toolsets:
  - type: lsp
    command: rust-analyzer
    file_types: [".rs"]

C/C++ (clangd)

toolsets:
  - type: lsp
    command: clangd
    file_types: [".c", ".cpp", ".h", ".hpp"]

Multiple LSP Servers

You can configure multiple LSP servers for different file types:

agents:
  polyglot:
    model: anthropic/claude-sonnet-4-5
    description: Multi-language developer
    instruction: You are a full-stack developer.
    toolsets:
      - type: lsp
        command: gopls
        file_types: [".go"]
      - type: lsp
        command: typescript-language-server
        args: ["--stdio"]
        file_types: [".ts", ".tsx", ".js", ".jsx"]
      - type: lsp
        command: pylsp
        file_types: [".py"]
      - type: filesystem
      - type: shell

Workflow Instructions

The LSP tool includes built-in instructions that guide the agent on how to use it effectively. The agent learns to:

1. Start with lsp_workspace to understand available capabilities
2. Use lsp_workspace_symbols to find relevant code
3. Use lsp_references before modifying any symbol
4. Check lsp_diagnostics after every code change
5. Apply lsp_format after edits are complete

Tip

Best Practice

Always include the filesystem tool alongside LSP. The agent needs filesystem access to read and write code files, while LSP provides intelligence about the code.

Capability Detection

Not all LSP servers support all features. During the initialize handshake, docker-agent reads the server's ServerCapabilities and filters out the lsp_* tools the server does not advertise. The model never sees, for example, lsp_inlay_hints against a server that doesn't support it, so it can't waste a turn calling a tool that would only fail.

The agent uses lsp_workspace to discover what's available:

Workspace Information:
- Root: /path/to/project
- Server: gopls v0.14.0
- File types: .go

Available Capabilities:
- Hover: Yes
- Go to Definition: Yes
- Find References: Yes
- Rename: Yes
- Code Actions: Yes
- Formatting: Yes
- Call Hierarchy: Yes
- Type Hierarchy: Yes
...

Auto-Restart and Lifecycle

LSP toolsets are managed by the same supervisor as MCP toolsets, so a crashed gopls (or any other language server) is reconnected automatically with exponential backoff. Use the lifecycle block to tune the policy per toolset — for example, mark gopls as strict if your CI flow requires it to be available, or use /toolset-restart gopls from the TUI to force a reconnect when the server gets stuck.

toolsets:
  - type: lsp
    command: gopls
    file_types: [".go"]
    lifecycle:
      profile: resilient # default: auto-restart on crash with exponential backoff

Position Format

All LSP tools use 1-based line and character positions:

• Line 1 is the first line of the file
• Character 1 is the first character on a line

{
  "file": "/path/to/file.go",
  "line": 42,
  "character": 15
}

Tip

Auto-Installation

docker-agent can automatically download and install LSP servers if they are not found in your PATH. Use the version property to specify a package, or let docker-agent auto-detect it from the command name. See Auto-Installing Tools for details.