Text search is useful until an AI coding agent has to answer a structural question: where is this symbol really defined, which callers will a refactor affect, or what type does this expression have? A grep result can show matching text, but it cannot reliably distinguish a definition from a re-export, a comment, or an unrelated variable with the same name.
Locus MCP adds a small semantic layer to that workflow. It connects an MCP-compatible agent to language servers, so the agent can ask for definitions, references, hover information, diagnostics, status, and a rename preview through six focused tools.
This tutorial sets up Locus for a TypeScript project, checks the language-server boundary, and adds an MCP configuration that an agent host can start automatically. The goal is not to replace an IDE or make refactors autonomous. The goal is to give an agent better evidence before it edits code.
Install a language server, run Locus initialization and checks, then add the server to your agent configuration:
npm install -g typescript-language-server typescript
npx -y @paladini/locus-mcp init
npx -y @paladini/locus-mcp check
The current npm package is @paladini/locus-mcp@0.1.5 and requires Node.js 22 or newer. Pin that version in repeatable setup scripts when you do not want a moving latest tag.
You need:
PATH.
For TypeScript and JavaScript, the repository documents typescript-language-server and typescript. Python, Go, and Rust use separate language servers described in the Locus getting started guide.
Locus itself does not bundle those language servers. That separation matters: Locus provides the MCP and LSP client layer, while the language server remains an independently installed tool with its own version and configuration.
Install the TypeScript language server globally, then initialize the project from its root:
npm install -g typescript-language-server typescript
npx -y @paladini/locus-mcp init
The documented init command generates locus.toml and locus.json without replacing existing configuration files. Keep the generated files under version control if the project team wants a shared language-server setup. Use a project-scoped configuration when different repositories need different server choices.
Now check whether the required binaries are visible:
npx -y @paladini/locus-mcp check
The check is intentionally honest. It reports available and missing binaries instead of pretending that a language can be analyzed. A missing server is a setup problem, not an LLM failure.
Before connecting an agent, inspect the generated files. A minimal configuration can look like this:
{
"root": ".",
"servers": [
{
"id": "typescript",
"command": "typescript-language-server",
"args": ["--stdio"],
"extensions": [".ts", ".tsx", ".js", ".jsx"]
}
]
}
The exact schema and built-in defaults are maintained in the Locus configuration reference. When the server list is empty, Locus uses built-in defaults. Custom entries are useful when a project needs a non-default binary, additional arguments, or a narrower extension mapping.
The package also exposes a status MCP tool. It reports language-server readiness and missing binaries, while diagnostics can report file or workspace problems. These results should be treated as evidence with a scope and a timestamp, not as a guarantee that the whole project is correct.
Locus is normally started by the host over stdio. You do not need to run serve manually for the normal MCP configuration.
For Cursor, create or edit .cursor/mcp.json in the project:
{
"mcpServers": {
"locus": {
"command": "npx",
"args": ["-y", "@paladini/locus-mcp@0.1.5", "serve"],
"cwd": "/absolute/path/to/your/project"
}
}
}
For Codex, the repository documents the equivalent TOML configuration:
[mcp_servers.locus]
command = "npx"
args = ["-y", "@paladini/locus-mcp@0.1.5", "serve"]
cwd = "/absolute/path/to/your/project"
Use the host's normal reload or restart action after saving the configuration. Then ask the agent to locate a symbol and list its references. A useful first request is: "Use Locus to find the definition of UserService and list its references."
The value is not the number six. It is the division of labor between the agent and the language server:
locate finds a symbol definition or lists symbols in a file.refs finds references or implementations at a position.hover returns type information and documentation.diagnostics reports file or workspace diagnostics.status shows server readiness and binary availability.rename previews a rename and can return an apply plan.
That last tool is worth treating carefully. A rename preview is not the same as an approved write. Locus can prepare a plan, but your agent still decides whether and how to apply edits. This keeps the tool focused on code intelligence instead of turning it into an autonomous refactoring system.
You can verify the installation without asking an agent to edit your repository:
npx -y @paladini/locus-mcp init
npx -y @paladini/locus-mcp check
npx -y @paladini/locus-mcp warm
init is idempotent according to the repository's CLI tests, so running it again should preserve existing configuration. warm starts configured language servers early, which can make the first semantic request less surprising on a larger project. If a binary is missing, check can return a non-zero status. Install the missing language server and run the check again.
For a source-level verification of the project itself, the repository's current main checkout passed npm run build, npm run typecheck, and npm test. The test suite reported 94 passing tests and one skipped integration case because pyright-langserver was not installed in that environment. The same suite verified the TypeScript language-server integration and the six-tool MCP registration. These are repository checks, not a promise that every host or language configuration will behave identically.
Run locus check first. If the language server is missing, not executable, or mapped to the wrong file extension, semantic requests cannot succeed. Also confirm that the host passes the intended project directory through cwd.
Language servers may need time to index a workspace. Locus exposes a server_starting result so the client can retry rather than treating a temporary startup state as a definitive absence of results. warm can move that startup earlier in the session, but it does not eliminate indexing cost.
Locus does not replace grep. The repository explicitly positions ordinary text search as the right tool for comments, configuration keys, log lines, and other non-symbol content. Use semantic tools for code structure and text search for literal content.
Locus reads project files through language-server processes and communicates with the agent host over stdio. It does not provide a security guarantee for a language server, an editor host, or a third-party plugin. Keep language servers and agent hosts updated, review MCP configuration before enabling it, and avoid granting a tool more filesystem scope than the project requires.
The project is MIT licensed, but dependencies and language servers have their own licenses and security posture. Read the repository's security policy and the MIT license before redistributing or deploying it in a managed environment.
No. Its tools provide navigation, diagnostics, status, and rename previews. Your agent's normal edit mechanism remains responsible for changing files.
The documented setup includes Cursor, Codex, and Claude Code. The deeper requirement is an MCP-compatible host that can start a stdio server with a project working directory.
No. Install only the servers for languages in the projects you want to analyze. status and check make missing binaries visible.
No. Locus intentionally exposes six focused tools and complements the host. The project documents symbolic editing, agent memory, and a broad refactoring toolkit as out of scope.
An AI coding agent becomes easier to review when it can cite structure instead of guessing from matching text. Locus provides that bridge with a small MCP surface, explicit language-server prerequisites, and a dry-run-oriented rename flow. Start with one TypeScript project, verify check and status, then decide whether the extra semantic evidence improves your agent's refactoring workflow.
What would you verify first in your own repository: definitions, references, diagnostics, or rename previews?
AI assistance disclosure: AI was used to help organize and edit this tutorial. The commands, package metadata, repository documentation, license, and test results were checked against the public Locus sources and a local checkout before publication.