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.

ℹ️ 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.

Configuration

agents:
  developer:
    model: anthropic/claude-sonnet-4-0
    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

Property Type Required Description
command string ✓ LSP server executable command
args array ✗ Command-line arguments for the LSP server
env object ✗ Environment variables for the LSP process
file_types array ✗ File extensions this LSP handles (e.g., [".go", ".mod"])

Available Tools

The LSP toolset provides these tools to the agent:

Tool Description Read-Only
lsp_workspace Get workspace info and available capabilities ✓
lsp_hover Get type info and documentation for a symbol ✓
lsp_definition Find where a symbol is defined ✓
lsp_references Find all references to a symbol ✓
lsp_document_symbols List all symbols in a file ✓
lsp_workspace_symbols Search symbols across the workspace ✓
lsp_diagnostics Get errors and warnings for a file ✓
lsp_code_actions Get available quick fixes and refactorings ✓
lsp_rename Rename a symbol across the workspace ✗
lsp_format Format a file ✗
lsp_call_hierarchy Find incoming/outgoing calls ✓
lsp_type_hierarchy Find supertypes/subtypes ✓
lsp_implementations Find interface implementations ✓
lsp_signature_help Get function signature at call site ✓
lsp_inlay_hints Get type annotations and parameter names ✓

Common LSP Servers

Here are configurations for popular languages:

Go (gopls)

toolsets:
  - type: lsp
    command: gopls
    file_types: [".go"]

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-0
    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
💡 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. 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
...

Position Format

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

{
  "file": "/path/to/file.go",
  "line": 42,
  "character": 15
}
⚠️ Server Installation

The LSP server must be installed and available in the system PATH. cagent does not install LSP servers automatically. Install them using your language's package manager (e.g., go install golang.org/x/tools/gopls@latest).

← Previous Model Routing