Connect Codex to Serena

What you get

Serena runs a real language server behind Codex instead of grep-and-read. Per Serena’s tools reference, the LSP-backed tool set includes:

• Navigation: find_symbol, find_declaration, find_implementations, find_referencing_symbols, get_symbols_overview, get_diagnostics_for_file
• Editing: replace_symbol_body, insert_before_symbol, insert_after_symbol, rename_symbol, safe_delete_symbol
• General purpose: read_file, create_text_file, replace_content, execute_shell_command, activate_project, write_memory

write_memory is Serena’s own project-memory system and has nothing to do with Codex’s.

Setup

1. Install Serena. The README and the installation page both give the same command:

uv tool install -p 3.13 serena-agent

That pulls the serena-agent package from PyPI, pinned to Python 3.13. Upgrade later with uv tool upgrade serena-agent.

Older third-party guides still show uvx --from git+https://github.com/oraios/serena serena start-mcp-server, which ran Serena straight out of the git repo. Neither the README nor the installation page mentions that form as of 2026-07-16. Nobody at Oraios has called it deprecated in the docs we read, so treat it as stale rather than dead and use the uv tool install line.

2. Wire it into Codex. Serena ships an installer for this client:

serena setup codex

Serena’s docs say that writes into ~/.codex/config.toml, the user-level config. To write the block by hand, use the one from those same docs:

[mcp_servers.serena]
startup_timeout_sec = 15
command = "serena"
args = ["start-mcp-server", "--project-from-cwd", "--context=codex"]

Per Serena’s configuration page, a context “defines the general environment in which Serena is operating” and “influences the initial system prompt and the set of available tools.” codex is one of five built-in contexts, alongside desktop-app, claude-code, ide, and agent. This is a stdio entry, so it takes command and never url. See Connect an MCP server for that distinction and the full key reference.

3. Confirm it loaded. Restart Codex, then run:

codex mcp list

Check that serena shows up initialized.

4. Activate the project each session. Serena’s docs are direct about this one: “The Codex app does not start a session in the project’s directory, so when using the app, we recommend asking Codex to ‘Activate the current dir as project using serena’ at the start of each session.” Their recommended fix is a chat instruction at the top of the session, not a flag you can set once.

Gotchas

Project-level config gets ignored (openai/codex #13025). Opened 2026-02-27, still open as of 2026-07-16, with 19 comments and 44 +1 reactions per the GitHub API. The title: “Codex Desktop ignores project .codex/config.toml MCP server (Serena) and only loads ~/.codex/config.toml.” If you hand-write a [mcp_servers.serena] block into a project’s own .codex/config.toml and expect Codex to pick it up per-project, Codex Desktop won’t read it. Only the user-level file loads. serena setup codex writes to ~/.codex/config.toml already, so install it once globally and use step 4 to point it at whatever project you’re in.

“request timed out” has hit this pairing before. oraios/serena #617 and #648 both report MCP client for 'serena' failed to start: request timed out under Codex CLI while the server started fine standalone. #617 was filed from Windows and WSL. Both are closed: #617 on 2025-09-12, #648 on 2025-12-17. #648 is titled “Dashboard being enabled causes timeouts/connection failures,” so check the dashboard setting first if you see this. The issue body doesn’t spell out the mechanism behind that correlation. Both closed months ago, so a timeout you hit today is more likely something new than a rerun of either.

The default startup window is tight. Serena’s own Codex block ships startup_timeout_sec = 15, above Codex’s documented 10-second default. There’s no cold npx download here, since uv tool install already put serena on your PATH. Keep the 15 anyway. The vendor put it there on purpose.

No auth to configure. This is a local stdio server, so there’s no bearer_token_env_var or OAuth flow to set up. Some language servers do need an environment variable. Serena’s docs cite F# on macOS with Homebrew and show "env": { "DOTNET_ROOT": "/opt/homebrew/Cellar/dotnet/9.0.8/libexec" }. That example is JSON, written for Claude Desktop. Codex wants TOML, and env lives in its own table:

[mcp_servers.serena.env]
DOTNET_ROOT = "/opt/homebrew/Cellar/dotnet/9.0.8/libexec"

See env vars for the syntax.

Related

• Connect an MCP server: the stdio vs. remote shape and the full key table
• startup_timeout_sec: what the 10-second default covers and when to raise it
• env vars for MCP servers: the [mcp_servers.<id>.env] table
• Install Codex CLI: if Codex itself isn’t set up yet