Serena MCP Agent Integration

Serena transforms LLMs into fully-featured coding agents with IDE-like intelligence by leveraging the Language Server Protocol (LSP) for structural code understanding.

Core Value Proposition

Capability	Benefit
Semantic code retrieval	Navigate by symbols, not text - 30x+ token reduction
Surgical editing	Modify function bodies while preserving structure
Project memory	Persist knowledge across sessions in `.serena/memories/`
Multi-client support	Claude Desktop, Claude Code, Codex, ChatGPT, custom agents

Project Lifecycle

1. Activation

Activate project before any operations:

"Activate the project /path/to/my_project"

First-time activation creates .serena/project.yml with default settings.

2. Onboarding

Run automatically on first session. Creates memories in .serena/memories/:

tech_stack_and_dependencies.md
code_style_and_conventions.md
task_completion_guidelines.md

If not auto-triggered:

"Start the Serena onboarding process for this project."

Critical: Start NEW conversation after onboarding (context fills up during analysis).

3. Indexing (Large Projects)

Pre-index to prevent tool timeouts:

serena project index

Run once; auto-updates during use.

Tool Usage Strategy

Priority Order (Prefer Higher):

Symbolic tools - Most efficient, LSP-powered
- get_symbols_overview → File structure without reading content
- find_symbol → Locate definitions precisely
- find_referencing_symbols → Impact analysis before changes
- replace_symbol_body → Rewrite functions safely
Line-based tools - When symbols don't apply
- replace_lines, insert_at_line, delete_lines
Full file operations - Last resort
- read_file, create_text_file

See: references/tools-reference.md for complete tool taxonomy.

Memory Management

Persist knowledge in .serena/memories/:

Tool	Purpose
`write_memory`	Save contracts, schemas, progress
`read_memory`	Load prior session context
`list_memories`	Discover available memories
`prepare_for_new_conversation`	Generate continuation summary
`summarize_changes`	Document session work

Pattern: End sessions with summarize_changes → write_memory.

Thinking Tools

Force self-reflection during complex operations:

Tool	When to Use
`think_about_collected_information`	Before implementing
`think_about_task_adherence`	During long operations
`think_about_whether_you_are_done`	Before declaring complete

Client Configuration

Claude Desktop: Edit claude_desktop_config.json

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena",
               "serena", "start-mcp-server", "--context", "desktop-app"]
    }
  }
}

Claude Code: From project directory:

claude mcp add serena -- uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context ide-assistant --project "$(pwd)"

See: references/client-setup.md for Codex, ChatGPT, Docker, etc.

Contexts and Modes

Contexts (set at startup, immutable):

desktop-app - Claude Desktop (full toolset)
claude-code - Claude Code (no duplicates)
ide-assistant - IDE extensions (minimal tools)
codex - OpenAI Codex
chatgpt - ChatGPT via MCPO

Modes (combinable, switchable):

editing + interactive - Standard development (default)
planning - Analysis before implementation
one-shot - Single-response tasks
no-onboarding - Skip if memories exist

Switch dynamically: "Switch to planning mode"

See: references/contexts-and-modes.md for full reference.

Security Configuration

In .serena/project.yml:

read_only: true  # Disable all editing (analysis only)
excluded_tools:
  - execute_shell_command  # Always disable for untrusted contexts

Non-negotiables:

Use version control (Git) for all projects
Disable execute_shell_command unless explicitly needed
Set read_only: true for code review/analysis tasks
Never expose MCPO API keys

Debugging Framework

For complex automation workflows (n8n, Zapier, etc.):

Behavior Contract - Document expected behavior before changes
Snapshot Before - Capture current state
Parity Grid - Map contract → current → fix required
Dry-Run - Validate changes before applying
Apply + Validate - Execute with proof
Memory Harden - Persist final state

See: references/debugging-framework.md for canonical prompts and workflow.

Session Protocol

Start:

Verify project activation: get_current_config
Check onboarding: check_onboarding_performed
Load relevant memories: list_memories → read_memory
Run build/type-check command (establish baseline)

During:

Read files BEFORE editing (prevent duplicates)
Use symbolic tools preferentially
Run validation after each change
Use thinking tools for complex tasks

End:

Final validation (build/lint/test)
summarize_changes → write_memory
For continuation: prepare_for_new_conversation

When to Use Serena

Optimal:

Large/complex/legacy codebases
Refactoring across multiple files
Analyzing dependencies and architecture
Token-sensitive operations

Not Needed:

New empty projects (nothing to analyze)
Single-file scripts
When entire context fits easily

Dashboard

Monitor operations at: http://localhost:24282/dashboard/index.html

View: tool calls, logs, configuration, active languages.

serena-mcp-agent