Troubleshoot Lens Studio MCP
Fix an AI coding assistant that can't connect to the Lens Studio MCP server, can't see its tools, or can't find the CLAD plugin.
Find the symptom, then work through its fix. Most connection problems come from starting the assistant before Lens Studio, or from the server's port changing after Lens Studio restarts.
Check the setup first
The connection steps differ by assistant: see Set Up CLAD in Claude Code, Set Up CLAD in Codex, or Set Up CLAD in Cursor. Check that Lens Studio is open with your project.
When building for SPECS, also check that the project targets SPECS: see Convert a Project to SPECS.
The assistant doesn't list the lens-studio server
Cause: the assistant didn't start in the project folder, or started before Lens Studio wrote the connection file.
Fix:
- Open the project in Lens Studio, and check that the server is running: select AI Assistant > AI Model Context Protocol (MCP) > Configure Server and look for Server running.
- Check that the project folder has the connection file for your assistant:
.mcp.json(Claude Code),.codex/config.toml(Codex),.cursor/mcp.json(Cursor), or.vscode/mcp.json(VS Code). - Quit the assistant, open a terminal with File > Show Project in Terminal, and start the assistant again from there.
Cursor lists the server but leaves it off until you turn it on in Customize. VS Code starts it only in a trusted folder.
The connection is refused (ECONNREFUSED)
Failed to reconnect to lens-studio: ECONNREFUSED at http://localhost:50041
Cause: the assistant is calling a port the server no longer uses. The port can change when Lens Studio restarts, and an MCP entry you added by hand keeps the old one.
Fix:
- Select AI Assistant > AI Model Context Protocol (MCP) > Configure Server and read
the address under Server running, such as
http://localhost:50040/mcp. - If you added the server by hand, update its URL to that address, or select Copy MCP Config and replace the entry. The connection files Lens Studio writes into the project folder already have the new port.
- Reconnect in the assistant (
/mcpin Claude Code and Codex).
You can also paste the copied config into the assistant and ask it to fix the connection. For example: "Connect to Lens Studio MCP using this configuration: [pasted config]".
The server stopped or won't start
In Configure Server, select Restart Server, or Start Server if the status says the server is stopped. Then restart the assistant, or reconnect it, so it picks up the server again.
The assistant connects but has few or no Lens Studio tools
Cause: a Lens Studio plugin that provides the tools is turned off.
Fix:
- Select Lens Studio > Preferences > Plugins.
- Under Installed Plugins, search for and turn on:
- Core ChatTools, which provides the Lens Studio tools.
- Agents Docs, which writes the connection files and
AGENTS.md.
- Reconnect the assistant.
To check, ask the assistant whether it can use the ExecuteEditorCode tool. If it can, it has the
full set.
The CLAD skills aren't available in the assistant
Cause: the CLAD plugin isn't installed, or the assistant hasn't loaded it yet.
Fix: reload or restart the assistant; some assistants find a new plugin only after a restart.
Some install a plugin without turning it on, so check that it's enabled. Then check its plugin list for ls-clad: /plugin in
Claude Code, /plugins in Codex, Customize in Cursor. If it's missing, install it again with
your assistant's setup page: Set Up CLAD in Claude Code,
Set Up CLAD in Codex, or Set Up CLAD in Cursor.
The ls-extensions repository has the latest
installation steps.
Related
- Connect Your Agent to Lens Studio: the server and its connection files.
- What Is CLAD: what the plugin adds.