Serena MCP: how to give your agent semantic navigation in VS Code

The project documentation describes symbol search and edit operations, plus support for more than 40 languages through language servers. Serena is not an AI model and does not work alone: the agent remains responsible for interpreting the request and deciding which tools to use.

How Serena connects to the agent

Serena can expose its tools to MCP compatible clients, including VS Code and other programming environments. In the standard backend, it uses language servers to understand symbols and relationships in code. There is also a plugin based backend for JetBrains, with its own features; check the overview of options before choosing.

This is different from simply adding another generic server. Serena offers operations such as locating symbols and references, querying file structure and performing some symbolic edits. Capabilities vary by language and configured backend; not every operation exists for all language servers.

Install Serena

The official installation documentation uses uv as manager. Install the package and initialize the tool:

$ uv tool install -p 3.13 serena-agent
$ serena init

The parameter -p 3.13 selects Python 3.13 for the installation. serena init configures the default language server backend; some languages may require additional dependencies, listed on the language support page.

Connect to VS Code

In VS Code, open the Command Palette and choose MCP: Add Server. Select Command (stdio) and configure Serena for the current workspace with:

serena start-mcp-server --context=vscode --project ${workspaceFolder}

This is the per workspace option described in the official guide for MCP clients. It limits the configuration to the open project and allows Serena to recognize it automatically.

It is also possible to configure Serena globally with serena start-mcp-server --context=vscode. The documentation states that, due to a VS Code limitation, this option may not activate the project on its own. In that case, ask the agent at the start of the session: “Activate the current directory as a project using Serena”. Then check if the server and tools appear in the chat area.

To understand general configuration options in the editor, see our MCP guide in VS Code. And combine semantic navigation with well scoped project instructions using the article about AGENTS.md.

Security limits and license

Serena can offer the agent tools that modify files and run commands. The maintainer states that untrusted projects are not automatically sandboxed: trust rules limit some influences from the repository, but they are not a containment boundary. For code of dubious origin, use an isolated environment and review each action. See the official security considerations.

It is also important to check the license before redistributing or integrating the software. The license is per component: SolidLSP, the base of the code intelligence backend, is under MIT; the Serena application, including MCP server and tools, is under GPL-3.0-or-later as of the transition from version 2. Distribution that combines the components, such as the package serena-agent, is under GPL-3.0-or-later. See the official license explanation.