AI coding agents need code intelligence to be effective. Relying on simple file reads and grep searches works for small scripts, but it falls apart quickly in a real codebase.
Connecting agents to Language Server Protocol (LSP) servers is not a new idea. Developer tools like Cursor, Claude Code, and Aider have integrated LSP capabilities to give their agents IDE-grade navigation (go to definition, find references, rename symbols). But for users running autonomous teams on the OpenClaw platform, these capabilities were missing.
We recently bridged this gap by integrating Serena, a Python-based LSP bridge designed as a Model Context Protocol (MCP) service, into OpenClaw. This turned a standalone MCP service into a fully integrated OpenClaw plugin, unlocking significant token savings and accuracy improvements for our agent teams.
The Plugin Architecture
Serena is built by the Oraios team, and it provides an excellent, clean bridge between real LSP servers (TypeScript, Python, etc.) and the MCP protocol. Because OpenClaw speaks MCP natively, the foundational communication layer was already there.
Our work focused on the OpenClaw plugin integration and lifecycle management. Running a persistent Python subprocess that manages a TypeScript language server introduces statefulness that agents are not typically prepared to handle.
We built the serena-lsp plugin for OpenClaw to handle the operational reality of running an LSP:
- Process Lifecycle & Watchdog. The plugin manages the Serena subprocess, providing health checks via
tools/listheartbeats and exponential backoff for restarts. If the TypeScript LSP hangs during a massive indexing operation, the watchdog catches the timeout and restarts it cleanly. - Tool Mapping. Serena exposes its own MCP tool names, but we map them to feel native inside OpenClaw (
find_symbol,find_references,get_symbols_overview). The plugin handles parameter validation and automatically injects project-path context, so the agents do not need to reason about Serena’s internal configuration. - Cold Start Queueing. A TypeScript language server needs to index the project before it can answer queries. We added an LSP warmup step during the plugin startup. Any agent tool calls made during this indexing window are queued until initialization completes, rather than failing with timeout errors.
The plugin source code is available in our Shared Plugins Repository.
The Companion Skill
Providing the tools is only half the battle. If you hand an agent a find_symbol tool, it will often still default to running cat on a 2,000-line file because that is what its base training reinforced.
To solve this, we wrote a companion AgentSkill for OpenClaw: the Serena LSP Guide.
This skill acts as the agent’s behavioral manual. It explicitly instructs SWE agents to use the LSP tools instead of reading files directly. It teaches them to map their intentions (“I need to understand this module”) to the correct sequence of tools (get_symbols_overview followed by targeted find_symbol calls).
The Hard Data: Efficiency Gains
Before integrating Serena, our backend agent would routinely read 3 to 5 full files to understand the impact of a change. For a file like our 1,600-line scheduler.ts, that meant burning 4,000 to 8,000 tokens of source code per task, just to establish context.
After deploying the Serena plugin and the companion skill, we measured the difference:
- Token Reduction: The same tasks now use
get_symbols_overviewplus targetedfind_symbolcalls. This consumes roughly 200 to 500 tokens of structured metadata per task. That is a 10x to 15x reduction in code-understanding token spend. - Accuracy Improvement: Agents stopped making edits based on wrong assumptions about code structure. They now verify references before changing function signatures.
- Refactoring Safety: The
rename_symboltool saved us from a persistent class of bugs where agents would rename a function in one file but miss an import in another directory. The LSP handles the rename atomically across the entire project.
When you multiply these savings across a team of 15 specialized agents working concurrently, the impact on steady-state operating costs and merge success rates is massive.
Credits
This integration was entirely dependent on the heavy lifting done by the Oraios team on Serena. They built a robust, well-engineered bridge that translates complex LSP interactions into clean MCP tool calls. If you are building agentic systems that work with code, Serena is an exceptional project.
The OpenClaw platform provided the extensible plugin system and MCP client that made the integration straightforward, allowing us to focus on lifecycle management rather than protocol parsing.