Codex LSP Bridge (MCP)

Give Codex CLI IDE-grade semantic navigation by exposing Language Server Protocol (LSP) features as MCP tools.

What you get

Go to definition / type definition / find references
Hover / signature help / call hierarchy
Document symbols / workspace symbols
Code actions (autofix/refactors) / format document
Works across Python, Rust, C/C++, TypeScript/JavaScript/Node, React (JSX/TSX), HTML, CSS/SCSS/Less
One endpoint: http://127.0.0.1:8000/mcp (Streamable HTTP) or stdio

Quickstart

1) Install this bridge

# from the repo root
pip install -e .

2) Install language servers

On Debian/Ubuntu you can run ./install.sh to install all supported language servers.

Python (pick one)

pip install basedpyright   # provides basedpyright-langserver
# OR
npm i -g pyright           # provides pyright-langserver

Rust

rustup component add rust-analyzer

C/C++

# install clangd via your platform (llvm package)
clangd --version

TypeScript/JavaScript/Node/React

npm i -g typescript typescript-language-server

HTML/CSS

npm i -g vscode-langservers-extracted

3) Run the server

codex-lsp-bridge serve --config ./config/default.toml --host 127.0.0.1 --port 8000

4) Connect Codex CLI

Edit ~/.codex/config.toml (HTTP):

experimental_use_rmcp_client = true

[mcp_servers.lsp_bridge]
url = "http://127.0.0.1:8000/mcp"

Or use the Codex CLI helper:

codex mcp add lsp_bridge --url http://127.0.0.1:8000/mcp

Using it effectively

Prompt pattern:

When navigating or refactoring code, always use LSP tools instead of text search.

Example:

codex "Find all references to UserRepository and rename it to AccountRepository. Use LSP rename_symbol first."

Note: line/column positions are 0-indexed. Tip: if line/column might be off, pass fuzzy=true (and optionally fuzzy_radius) to position-based tools.

LSP tool coverage

Core tools:

go_to_definition, type_definition
find_references, rename_symbol
hover, signature_help
document_symbols, workspace_symbols
code_action, format_document
call_hierarchy, diagnostics, wait_for_diagnostics, lsp_bridge_status
resolve_symbol (fuzzy name-based lookup)

Smoke test (no file changes)

You can run a quick LSP smoke test against any file:

python scripts/lsp_smoke_test.py --file /abs/path/to/file.py --line 10 --column 5

Add --call-hierarchy if you want to test call hierarchy responses.

Install language servers (Debian/Ubuntu)

If you are on Debian/Ubuntu, you can use the provided script:

./install.sh

This installs:

basedpyright (Python)
ruff + ruff-lsp (Python lint/autofix)
rust-analyzer (Rust)
clangd (C/C++)
typescript-language-server + typescript (TS/JS/React)
vscode-html-language-server + vscode-css-language-server (HTML/CSS)
eslint (JS/TS lint)

Note: some commands may land in ~/.local/bin or ~/.cargo/bin. Ensure those are on PATH for the user that runs the bridge.

Config

See config/default.toml. It maps file extensions to language server commands.

For Python, config/default.toml also enables stronger type checking settings and excludes large folders like .venv to keep the LSP responsive.

You can point the bridge to a config file via:

export CODEX_LSP_BRIDGE_CONFIG=/path/to/config.toml

MCP setup (HTTP vs stdio)

HTTP (bridge runs separately):

experimental_use_rmcp_client = true

[mcp_servers.lsp_bridge]
url = "http://127.0.0.1:8000/mcp"

Stdio (Codex spawns the bridge, no HTTP):

[mcp_servers.lsp_bridge]
command = "/absolute/path/to/codex-lsp-bridge"
args = ["serve", "--transport", "stdio", "--config", "/absolute/path/to/config/default.toml"]

Multi-project behavior

Each tool call includes a file_path.
The bridge detects the workspace root by walking upward from that file and looking for markers like .git, package.json, Cargo.toml, etc.
It starts an LSP per (language, workspace_root) so multiple repos do not contaminate each other.
Absolute paths are recommended; relative paths resolve against the bridge's default_root.

You can also force a workspace root by passing workspace_root to any file-based tool call.

Autofix + lint + strong types

The code_action tool returns quick fixes and refactors when a language server supports them. For best results per language:

Python: basedpyright/pyright for types. For lint+autofix, consider switching to ruff-lsp or pylsp with ruff/black plugins.
TypeScript/JavaScript: types come from typescript-language-server and your tsconfig.json (use strict: true for strong types). For lint/autofix, use ESLint and its LSP server.
Rust: rust-analyzer provides strong types and code actions (e.g., import/quickfix).
C/C++: clangd provides diagnostics and some fixes; accuracy depends on compile_commands.json.

System prompt snippet

See SYSTEM_PROMPT_SNIPPET.md for a short snippet you can append to your AI system prompt so it always prefers LSP tools.

Security notes

Local is safest: the bridge reads your repo files and launches local binaries.
If you deploy remotely, only do so where the server has access to the same repo and protect it with auth.

Codex LSP Bridge