Client Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Serena is designed to extend existing AI clients via the Model Context Protocol (MCP). The configuration system allows Serena to integrate seamlessly with various clients—such as terminal-based CLI agents, IDE plugins, and desktop applications—by providing specific launch commands and execution contexts.
The configuration architecture is multi-layered, supporting global settings, project-specific overrides, and client-specific setup handlers. This ensures that the agent operating within a specific client (e.g., Claude Code or Codex) receives the correct set of tools and behavioral prompts optimized for that environment.
Sources: README.md:92-108, src/serena/config/serena_config.py:114-124
Automated Client Setup
Serena provides a specialized ClientSetupHandler framework to automate the registration of Serena as an MCP server within supported clients. This system detects if a client is installed on the host machine and generates the appropriate configuration commands to link the two.
Client Setup Architecture
The setup process follows a standardized lifecycle: detection, option generation, and application via shell commands.
The diagram shows the logic flow for registering Serena as an MCP server within a specific client.
Sources: src/serena/config/client_setup.py:6-43, src/serena/cli.py:109-130
Supported Client Handlers
Currently, Serena includes specialized handlers for popular CLI-based agents.
| Client | Detection Method | Default Options | Registration Command |
|---|---|---|---|
| Claude Code | claude --version | --context=claude-code, --project-from-cwd | claude mcp add --scope user serena -- [cmd] |
| Codex | codex --version | --context=codex, --project-from-cwd | codex mcp add serena -- [cmd] |
Sources: src/serena/config/client_setup.py:46-81
Context-Specific Configuration
When starting the MCP server, users can specify a --context. This context defines the system prompts and tool availability optimized for the specific client being used.
MCP Server Launch Options
The serena start-mcp-server command supports several flags that influence client behavior:
--context: Selects a built-in context (e.g.,claude-code,codex) or a custom YAML.--project-from-cwd: Automatically detects the project root by searching for.serena/project.ymlor.gitup from the current working directory.--transport: Supportsstdio(default for most CLI clients),sse, orstreamable-http.--mode/--add-mode: Activates specific tool layers (e.g.,editing,interactive).
Sources: src/serena/cli.py:134-210, src/serena/config/serena_config.py:145-155
Connection Flow
When a client connects to Serena, the following sequence occurs to establish the operating environment:
The diagram illustrates how the CLI uses the context and configuration files to initialize the agent for the connecting client.
Sources: src/serena/cli.py:214-250, src/serena/config/serena_config.py:440-460, README.md:112-120
Configuration Hierarchy
Client configuration is influenced by a composable hierarchy. Settings defined at the client launch level often override project and global settings.
- Global Configuration (
serena_config.yml): Defines default language backends (LSP/JetBrains), log levels, and trusted paths. - Project Configuration (
project.yml): Specifies languages, ignored paths, and default modes for a specific codebase. - Client Launch Command: CLI flags passed during the MCP server startup take the highest precedence.
Key Configuration Elements
| Field | Description | Source |
|---|---|---|
language_backend | Determines if Serena uses LSP or JetBrains IDE for analysis. | src/serena/config/serena_config.py:165-177 |
symbol_info_budget | Time limit (seconds) for retrieving docstrings/params during tool calls. | src/serena/resources/serena_config.template.yml:148-158 |
project_serena_folder_location | Template for where .serena metadata is stored (supports $projectDir). | src/serena/config/serena_config.py:535-555 |
read_only | Disables all editing tools for a specific project connection. | src/serena/resources/project.template.yml:92-95 |
Summary
Client configuration in Serena is centered around the Model Context Protocol, enabling a variety of AI tools to leverage semantic code understanding. By using automated setup handlers for clients like Claude Code and Codex, and providing a flexible CLI for launching the MCP server with specific contexts, Serena ensures that agents operate with the correct toolsets and behavioral constraints for their specific environment. This multi-layered configuration approach allows for global consistency while providing the granular control necessary for complex, multi-language codebases.
Sources: README.md:104-118, src/serena/cli.py:75-107