Serena を Codex に接続してシンボル単位で編集する手順

Serena とは何か — Codex に足りない「コードの地図」を補う

Serena は、コーディングエージェントに対して IDE に近い意味的な操作能力を与えることを目的とした MCP ツールキットだ。公式リポジトリ（https://github.com/oraios/serena）の説明によれば、Serena はコードを自前でパースするのではなく、VS Code の「定義へ移動」などを支えているものと同じ言語サーバー（LSP）プロセスを起動し、その応答を MCP のツール結果へ翻訳する。Python・Java・TypeScript・Rust など 40 以上の言語に対応しており、対応言語であれば同じ操作感で扱える。

ここが通常の Codex 単体の挙動との大きな違いだ。Codex はファイルを開いてテキストとして読むのが基本で、巨大なファイルや多数のファイルにまたがる構造を把握しようとするとコンテキストを大量に消費する。Serena を挟むと、Codex は関数やクラスといったシンボルの単位でコードを指し示せるようになり、必要な箇所だけを取り出して読み書きできる。エージェントが扱うのは「ファイルの何行目」ではなく「どのシンボル」かになるため、編集の組み合わせが壊れにくく、レビューもしやすい。Codex に正確な「コードの地図」を与える層、と捉えると役割が分かりやすい。

Serena を Codex に接続する手順

接続は三つの段階に分かれる。インストール、Codex への MCP サーバー登録、そしてプロジェクトの有効化だ。順を追って進めれば、特別な前提知識がなくても接続まで到達できる。

Step 1: Serena をインストールする

最初に Serena 本体を用意する。Python のパッケージ管理ツール uv を使う場合、uv tool install -p 3.13 serena-agent でインストールできる。uv をすでに導入済みなら、これだけで serena コマンドが使えるようになる。インストール後に対応言語のプロジェクトで動かすと、Serena が必要な言語サーバーを背後で起動して準備を整える。最初の起動時は言語サーバーの初期化に少し時間がかかるため、すぐに応答が返らなくても待つのがコツだ。

Step 2: Codex に MCP サーバーとして登録する

最も簡単なのは、Serena が用意している専用コマンド serena setup codex を実行する方法だ。これで Codex 用の設定が自動で書き込まれる。手動で設定したい場合は、~/.codex/config.toml に次のブロックを追記する。

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

--context=codex は Codex 向けにツールの説明文や挙動を最適化する指定で、--project-from-cwd は現在の作業ディレクトリを対象プロジェクトとして扱う指定だ。Codex の MCP 設定には、このようにローカルプロセスを起動する STDIO 型と、アドレスへ接続する HTTP 型の二種類がある（https://developers.openai.com/codex/mcp）。Serena はローカルで言語サーバーを動かす都合上、STDIO 型で登録するのが基本になる。なお他の MCP サーバーを汎用的に追加する場合は、codex mcp add <name> -- <起動コマンド> の形式が用意されている。

Step 3: プロジェクトを有効化して接続を確認する

設定後、Codex のセッション内で /mcp を実行すると、現在接続されている MCP サーバーの一覧が表示される。ここに Serena が出ていれば接続は成功だ。CLI から作業ディレクトリ内で起動した場合は --project-from-cwd の指定によって対象プロジェクトが自動的に定まるが、Codex のアプリ版はプロジェクトディレクトリでセッションを開始しないため、セッションごとに「このリポジトリを対象として有効化してほしい」と最初に依頼する必要がある。有効化が済むと、以降の指示で Serena のシンボル検索や編集ツールが使われるようになる。

Serena が提供する主なツールと使いどころ

Serena が Codex に渡すツールは、IDE で日常的に使う操作とよく対応している。代表的なものとして、シンボルの定義位置を探す検索、あるシンボルがどこから参照されているかを集める参照一覧、シンボル名のパスを指定して本体だけを置き換える編集、ファイル内の構造（クラスやメソッドの一覧）を概観する取得などがある。いずれも行番号ではなくシンボル名で対象を指すため、コードが少し動いても指定が壊れにくい。

実務での使いどころは明確だ。たとえば「ある関数の名前を変えたい」という依頼では、まず参照一覧ツールで呼び出し箇所を洗い出してから、影響範囲を確認したうえで編集に入れる。Codex 単体だと該当ファイルを順番に開いて確認する必要があり、見落としやコンテキスト超過が起きやすいが、Serena を通せば呼び出し箇所の地図を先に手に入れられる。新しい機能を既存コードに追加する場面でも、関連するクラスの構造をシンボル単位で取得してから設計を組み立てられるため、的外れな実装になりにくい。Serena 公式の利用ガイド（https://oraios.github.io/serena/02-usage/030_clients.html）でも、こうしたクライアント別の使い方が整理されている。

大規模コードベースで効果が出る理由

Serena の価値が最も際立つのは、ファイル数が多くテストやドキュメントが整ったリポジトリだ。小さなスクリプト一つを直す程度なら Codex 単体でも十分対応できるが、数百ファイル規模になると「どこを読むべきか」の判断そのものがボトルネックになる。Serena はこの判断を言語サーバーの正確な情報に置き換えるため、Codex が無駄に広い範囲を読み込んでコンテキストを使い切る事態を避けられる。読み込む量が減れば、その分を本来の思考や編集に回せる。

この利点は Codex v0.142 以降の並列ワークツリー機能と組み合わせると一層効いてくる。複数のタスクを同時に走らせるとき、各タスクが独立して正確にコードを把握できれば、タスク間の取り違えや重複した変更が起きにくい。シンボル単位の参照情報を共有の土台にすることで、並列で動くエージェントそれぞれが同じ「地図」を見ながら作業する状態に近づく。大規模リファクタリングや横断的な仕様変更のように、影響範囲の把握が成否を分ける作業ほど、Serena を挟む意味が大きくなる。

導入時のつまずきと対処

最初のつまずきは、言語サーバーの起動待ちを失敗と勘違いするケースだ。Serena は対象言語のサーバーを背後で立ち上げてから応答するため、初回は数十秒かかることがある。設定の startup_timeout_sec を短くしすぎると、準備が整う前に接続が切れたと判断されてしまう。応答が遅いと感じたら、まずはタイムアウト値に余裕を持たせて再試行するとよい。

次に多いのが、プロジェクトの有効化忘れだ。とくにアプリ版の Codex では、対象リポジトリを有効化しないまま依頼を出すと、Serena のツールが使われずに通常のファイル読み込みで処理されてしまう。/mcp で接続を確認したうえで、セッションの冒頭に対象プロジェクトを明示する習慣をつけると安定する。また、対応していない言語や生成物中心のディレクトリでは言語サーバーが十分な情報を返せないことがあるため、その場合は Serena に頼らず通常のファイル操作に切り替える判断も必要だ。どのツールが使われたかはセッションのログで確認できるので、意図通りに Serena が働いているかを時々見直すと運用が安定する。

まとめ

Serena は、Codex に IDE 並みのコード把握能力を与える MCP ツールだ。言語サーバーを使ってコードをシンボル単位で扱うため、Codex は行番号ではなく クラス名/メソッド名 の形で対象を指し示し、参照範囲を確認してから安全に編集できるようになる。接続は serena setup codex か ~/.codex/config.toml への設定追記で完了し、セッション内で対象プロジェクトを有効化すれば使い始められる。効果が大きいのはファイル数の多い中規模以上のリポジトリで、Codex v0.142 の並列ワークツリーと組み合わせると、複数タスクが同じ正確な「地図」を共有しながら作業できる。コンテキストの浪費を抑えつつ、影響範囲を把握したうえで変更を進めたい場面では、Serena を一度挟んでみる価値がある。