MCP Server Implementation
Relevant source files
The following files were used as context for generating this wiki page:
Serena implements a Model Context Protocol (MCP) server that acts as a bridge between AI agents and advanced coding tools. By exposing semantic code retrieval, symbolic editing, and refactoring capabilities through a standardized protocol, Serena enables agents like Claude Code or Codex to interact with codebases with IDE-level intelligence. The implementation leverages the fastmcp library to manage tool registration and server-client communication.
The MCP server is the primary interface for "agent-first" tool use, distinguishing itself by operating at the symbol level (classes, functions, methods) rather than simple text surgery. It supports various transport layers, including standard input/output (stdio) and Server-Sent Events (SSE), allowing it to integrate with terminal-based clients, IDE plugins, and desktop applications.
Sources: README.md:1-25, src/serena/mcp.py, server.json:1-10
Architecture and Components
The MCP architecture in Serena is centered around the SerenaMCPFactory, which is responsible for initializing the server and mapping internal Serena tools to MCP-compatible tool definitions.
SerenaMCPFactory
The factory handles the lifecycle of the MCP server, including configuration loading and tool registration. It ensures that the SerenaAgent is correctly initialized with the appropriate context and project settings before starting the server.
The diagram shows how the CLI triggers the factory to create a server instance by initializing a SerenaAgent and mapping its tools.
Sources: src/serena/mcp.py, src/serena/cli.py:270-325
Tool Mapping Process
Internal tools, derived from the Tool base class, are converted into MCPTool instances. This process involves extracting metadata from Python docstrings to populate descriptions and parameter schemas.
| Component | Responsibility |
|---|---|
make_mcp_tool | Static method to convert a Serena Tool to an MCP-ready tool. |
ToolRegistry | Maintains the list of available tools (e.g., find_symbol, get_symbols_overview). |
FastMCP | The underlying framework providing MCP protocol compliance. |
Sources: src/serena/mcp.py, test/serena/test_mcp.py:34-60
Communication and Lifecycle
The server follows a specific sequence for initialization and tool execution. Communication is handled via transport protocols defined at startup.
Initialization Sequence
When the server starts, it auto-detects projects or uses provided project paths to set up the environment.
This sequence illustrates the flow from initial client connection to the execution of a semantic tool call through the language backend.
Sources: src/serena/cli.py:326-348, src/serena/resources/config/prompt_templates/system_prompt.yml:40-60
Configuration and Transport
The MCP server can be configured via CLI arguments or the global serena_config.yml. It supports multiple transport mechanisms to accommodate different client requirements.
Transport Options
- stdio: Used for terminal-based clients like Claude Code. This is the default transport.
- sse: Server-Sent Events, used for web-based or remote integrations.
- streamable-http: For specific HTTP-based streaming requirements.
CLI Launch Command
The MCP server is typically started using the serena start-mcp-server command.
| Parameter | Type | Default | Description |
|---|---|---|---|
--project | PROJECT_TYPE | None | Path or name of project to activate. |
--context | string | DEFAULT_CONTEXT | Context YAML for tool instructions. |
--transport | Choice | stdio | stdio, sse, or streamable-http. |
--port | int | 8000 | Port for SSE/HTTP transport. |
--project-from-cwd | flag | False | Auto-detect project root from current directory. |
Sources: src/serena/cli.py:270-310, server.json:15-45
Tool Execution Logic
Tools are executed within the SerenaAgent context. The implementation ensures that tool descriptions are correctly formatted for LLM consumption, including return value descriptions extracted from docstrings.
# From src/serena/mcp.py (Conceptual logic derived from test_mcp.py)
def make_mcp_tool(tool_instance):
# Extracts name from tool class
name = tool_instance.get_name_from_cls()
# Extracts description from apply() docstring
description = tool_instance.apply.__doc__
# Maps apply() to the MCP execution function
return MCPTool(name=name, fn=tool_instance.apply_ex, description=description)
Sources: test/serena/test_mcp.py:34-75, src/serena/mcp.py
Integration with AI Clients
The server provides a cc_system_prompt_override specifically for Claude Code, instructing the agent to prioritize Serena's symbolic tools over built-in secondary tools like grep or read_file when dealing with code.
Required Workflow for Agents
- Discovery: Call
get_symbols_overviewto understand file structure. - Inspection: Call
find_symbol(include_body=true)for specific code reading. - Action: Use symbolic editing tools (
replace_symbol_body,rename,move) for modifications.
Sources: src/serena/resources/config/prompt_templates/system_prompt.yml:50-100, src/serena/resources/config/modes/editing.yml:10-30
Conclusion
Serena's MCP Server Implementation provides a robust, protocol-compliant bridge that elevates AI agents from simple text predictors to capable software engineers. By exposing IDE-like symbolic understanding through SerenaMCPFactory and SerenaAgent, it ensures efficient, context-aware code manipulation across diverse programming languages and development environments.