Skip to main content

Connect Locus to your AI assistant

Locus runs on your own computer and speaks a standard called MCP (Model Context Protocol) — think of it as a plug that lets an AI assistant ask Locus to search your files and get back real excerpts with sources, instead of guessing. You only need to do this setup once per assistant. Find yours in the list and click a platform to expand its steps.

How far we have tested each client

✓ Works with: full lifecycle(0)
Works with, plus edits, deletions, key revocation, reconnecting, the computer going offline, and removal.
✓ Works with(5)
We asked real questions through this client and saved the answers, which cited at least two files.
ConnectsNot yet verified(12)
We saw this client connect to a real Locus server. We have not yet recorded it answering questions.
Setup guideNot yet verified(12)
Setup steps written from the vendor's own docs. We have not yet finished a connection check with this client.

We only say Locus "works with" a client once it is marked Works with. Setup guide and Connects entries are labelled "Not yet verified": we have not yet recorded them returning cited answers from Locus. They are listed so you can try them.

Using a Chinese-market coding agent?

Kimi CLI, Kimi Code CLI, Qwen Code CLI, DeepSeek Harness, and ZCode are documented below — jump straight to that section.

Quickstart — from nothing installed to your first search, before you connect an AI assistant

You need a terminal. We recommend installing the engine with uv: you don't need Python installed first, because it installs its own. pipx works too if you already have Python 3.11+. The package is locusfiles and the command it adds is locus. These commands are for macOS and Linux; Windows is not yet verified:

curl -LsSf https://astral.sh/uv/install.sh | sh        # installs uv, then open a new terminal; skip if uv --version works
uv tool install --python 3.12 "locusfiles[local]"  # on-device embeddings, no account (adds PyTorch)
uv tool update-shell                      # adds ~/.local/bin to PATH; open a new terminal afterwards
#   or, with pipx instead of uv: pipx install "locusfiles[local]"
export LOCUS_EMBEDDER=local
locus doctor                              # checks Python, packages, settings and the embedder
locus index ~/Documents/notes --prune     # point it at any real folder of yours
locus query "what did I write about X" -k 5  # proves it works before you connect an assistant

That last command should print matching excerpts with file paths — if it does, indexing and search both work end to end, entirely on your own machine, no account and no API key involved (local is the default embedder). The free local mode is optimized for English; managed mode uses a multilingual model. We have not yet measured search quality in other languages. If anything fails, locus doctor names the exact broken check and the command that fixes it — same first step support would ask you to run.

Once that works, the rest of this page is about the other half: instead of typing locus query yourself, you let an AI assistant call the same search on your behalf — mid-conversation, with citations, as part of however you already work. That needs one more step, locus serve, wired into your assistant's own config — find your assistant below and click it to expand the exact steps.

Managed embeddings and remote connection also need a Locus API key from your dashboard: see the managed quickstart below. How to create a key, check it with a single command, and rotate it: API keys.

Managed quickstart — with a Locus plan or trial, no PyTorch

Managed embeddings come with a Locus plan or trial. The engine sends chunk text to Locus's relay instead of embedding on your computer, so you need neither PyTorch nor an embedding key of your own. On managed plans, chunk text and your search queries pass through Locus's relay to Voyage AI to be embedded. We don't store them; we keep only usage counts. You need a Locus API key from your dashboard (how to create one: API keys). New accounts are closed until paid plans open; join the waitlist to hear when they do. Install uv as in the quickstart above, then:

uv tool install --python 3.12 "locusfiles[relay]"

With pipx instead of uv: pipx install "locusfiles[relay]". Next, paste the line below on its own, paste your key at the prompt (nothing is shown) and press Enter. Do not paste it together with other commands: the terminal would read the next pasted line as if it were your key.

read -rs LOCUS_API_KEY; export LOCUS_API_KEY

Then run these lines one after another:

export LOCUS_EMBEDDER=managed
locus doctor
locus index ~/Documents/notes --prune
locus query "what did I write about X" -k 5

locus doctor confirms LOCUS_API_KEY is set for LOCUS_EMBEDDER=managed; locus index shows what it would send and asks before sending.

Your AI app starts its own locus serve and does not see what you exported in this terminal, so give it the same two settings, LOCUS_EMBEDDER=managed and LOCUS_API_KEY: in a JSON config, an "env" object next to "command"; in Claude Code, -e flags on claude mcp add. Already indexed with local? An index keeps one embedding model, so set a new LOCUS_COLLECTION (for example LOCUS_COLLECTION=managed) here and in your AI app's settings, and index again.

Anyone who holds your Locus API key can search and read your indexed files through the relay while your computer is serving, take over as your relay computer, spend your managed-embedding budget, and act as your account for up to ten minutes with each relay token they get from it. Keep it secret. If it leaks, revoke it from the dashboard, then check your key list again after ten minutes and revoke any key you did not create.

Remote connection — start the relay on your computer (Claude.ai and ChatGPT on the web)

A web AI app cannot start a program on your computer, so the computer that holds your index runs locus serve --transport relay and stays on and awake. It needs a Locus plan or trial, an index made as in the managed quickstart above, and the relay extra. Start the relay with the same LOCUS_EMBEDDER you indexed with, then add the connector in the Claude.ai or ChatGPT entry below.

In a terminal on that computer, first enter your Locus API key (paste it and press Enter; nothing is shown):

Shell
read -rs LOCUS_API_KEY

Then run these lines one after another:

Shell
export LOCUS_API_KEY
export LOCUS_EMBEDDER=managed
export LOCUS_MCP_RELAY_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImRtdHlicXRxdm5hZ3djZmZodXpyIiwicm9sZSI6ImFub24iLCJpYXQiOjE3ODk1NTYzMTgsImV4cCI6MjEwNTEzMjMxOH0.4MxlNEmBZXrmSQxoHBnFyjsFqqYIsZz1eZP4vdWgXzs
locus serve --transport relay

The LOCUS_MCP_RELAY_SUPABASE_ANON_KEY line is Locus's public relay key. It is not a secret: it is the same public value this website sends to every browser, and what you can reach through the relay is decided by your account, not by this key. Locus 0.1.3 and later fetch it from the relay themselves, so there you can leave the line out. With an older Locus the line is required: without it the command stops with "LOCUS_MCP_RELAY_SUPABASE_ANON_KEY is not set". To see which version you have, run uv tool list (or pipx list).

What this sends: When you reach your computer from another device or a web AI app, your question and the matching excerpts travel through Locus's relay (Vercel and Supabase) to and from your computer. They are encrypted in transit and we don't store them.

Anyone who holds your Locus API key can search and read your indexed files through the relay while your computer is serving, take over as your relay computer, spend your managed-embedding budget, and act as your account for up to ten minutes with each relay token they get from it. Keep it secret. If it leaks, revoke it from the dashboard, then check your key list again after ten minutes and revoke any key you did not create.

Jump to a platform(29)

Claude family

2 platforms
Claude DesktopConnectsNot yet verified

The easiest setup of all — no terminal needed after the one-time config step.

Last run 2026-09-16 · macOS · Locus server with 3 tools (older version)

If you use the Claude desktop app, this is the easiest setup of all — no terminal needed after the one-time config step below.

  1. Open Claude Desktop's settings and go to Settings → Developer → Edit Config. This opens a file called claude_desktop_config.json in a text editor.
  2. Add the following (if the file already has other content in it, merge this in rather than replacing everything):
    JSON
    {
      "mcpServers": {
        "locus": {
          "command": "/absolute/path/to/locus",
          "args": ["serve"]
        }
      }
    }
    The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.
  3. Fully quit Claude Desktop (not just close the window) and reopen it — this config is only read on startup.
  4. Start a new chat, click the tools icon (🔨) below the message box, and confirm "locus" is listed. Now ask a question that needs more than one of your indexed files — Claude will call Locus automatically and cite the files it used.
Claude Code✓ Works with

The CLI: one claude mcp add command registers Locus for every project.

Last run 2026-10-01 · macOS 26.3.1 · client version 2.1.273 · Locus 0.1.0 (5 tools)

Register Locus once for all your projects (--scope user), then check it from inside Claude Code:

Shell
claude mcp add --scope user locus -- /absolute/path/to/locus serve
claude              # start Claude Code in any folder
/mcp                # confirm "locus" shows Connected

The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.

Developers inside a Locus source checkout: its .mcp.json already registers Locus when you run claude from the checkout with its .venv activated.

Cursor, Devin Desktop & Cline

3 platforms
CursorConnectsNot yet verified

Project-level .cursor/mcp.json.

Last run 2026-09-16 · macOS · Locus server with 3 tools (older version)

  1. Create a file at .cursor/mcp.json in the root of the project you want to use Locus in (or ~/.cursor/mcp.json to have it in every project) with:
    JSON
    {
      "mcpServers": {
        "locus": {
          "command": "/absolute/path/to/locus",
          "args": ["serve"]
        }
      }
    }
    The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.
  2. Open Cmd+Shift+J (or Cursor menu → Settings → Cursor Settings) → the MCP tab, and confirm "locus" shows Connected with its tools listed.
  3. Make sure you're in Agent mode (not Ask-only) in the chat panel, then just ask your question — Cursor will call the tools for you.
Devin Desktop (formerly Windsurf)ConnectsNot yet verified

Cognition merged Windsurf into Devin Desktop. Connects to Locus; a full test with cited answers is not saved yet.

Last run 2026-09-18 · Locus server with 3 tools (older version)

Cognition merged Windsurf into Devin Desktop, and windsurf.com now redirects to devin.ai. The MCP configuration shape is the same one Windsurf used.

  1. Open the MCP config file. Devin's docs (read 2026-10-02) say the default Devin Local agent reads MCP servers from the Devin CLI config, ~/.config/devin/mcp_config.json, and the legacy Cascade agent uses the same file. The old Windsurf path is no longer the one to edit. We have not tested this path yet.
  2. Add a server entry equivalent to:
    JSON
    {
      "mcpServers": {
        "locus": {
          "command": "/absolute/path/to/locus",
          "args": ["serve"]
        }
      }
    }
    The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.
  3. Restart the app if it doesn't pick up the new server automatically, and confirm it lists Locus's tools, including locus_search, locus_list_sources and locus_read_file.
ClineConnectsNot yet verified

VS Code extension — MCP Servers icon in the sidebar. Connects to Locus; a full test with cited answers is not saved yet.

Last run 2026-09-18 · Locus server with 3 tools (older version)

  1. Click the MCP Servers icon in Cline's sidebar, then "Configure MCP Servers".
  2. Add a server entry equivalent to:
    JSON
    {
      "mcpServers": {
        "locus": {
          "command": "/absolute/path/to/locus",
          "args": ["serve"]
        }
      }
    }
    The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.
  3. Restart or reload the extension if it doesn't pick up the new server automatically, and confirm it lists Locus's tools, including locus_search, locus_list_sources and locus_read_file.

Former Roo Code users: Roo Code's VS Code extension shut down on 2026-05-15. Its team pointed users to Cline (the project Roo Code forked from) or Kilo Code, which can copy an existing .roo/mcp.json across.

Other coding agents & CLIs

8 platforms
GitHub Copilot (VS Code, JetBrains, Visual Studio)Setup guideNot yet verified

The IDE extension: .vscode/mcp.json with a servers key, not mcpServers. Written from GitHub's docs; the standalone CLI is the next entry.

Not run with Locus by us yet: steps written from the vendor's docs.

"GitHub Copilot" covers two different products with two different MCP config shapes. This entry is the IDE extension (VS Code, JetBrains IDEs, Visual Studio), which uses a top-level servers key — not mcpServers. The standalone terminal CLI (copilot) uses mcpServers in a different file and has its own entry. Copy-pasting one shape into the other's config file silently fails to register Locus.

Create or edit .vscode/mcp.json in your project (the github.com/copilot web chat has no custom-MCP support):

JSON
{
  "servers": {
    "locus": {
      "command": "/absolute/path/to/locus",
      "args": ["serve"]
    }
  }
}

The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.

Reload the IDE window and confirm Copilot Chat lists Locus as an available MCP server (usually via a tools/plug icon in the chat panel).

GitHub Copilot CLI✓ Works with

The standalone copilot CLI: mcpServers in ~/.copilot/mcp-config.json. With Copilot's hosted model it answered a test question citing two files (2026-10-01); local models are not verified.

Last run 2026-10-01 · macOS 26.3.1 · client version 1.0.86 · plan Copilot's hosted model (local models not verified) · Locus 0.1.0 (5 tools)

Install with npm install -g @github/copilot, then either hand-edit ~/.copilot/mcp-config.json (same mcpServers shape as the Claude Desktop entry) or use its own registration command:

Shell
copilot mcp add locus -- /absolute/path/to/locus serve
copilot mcp list   # or: copilot mcp get locus
The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.

In our test on 2026-09-21: after copilot login (device-code sign-in) and copilot mcp add locus -- ..., running copilot -p "list your available MCP tools" --allow-all-tools returned a live tool list including locus-locus_search, locus-locus_list_sources and locus-locus_read_file.

Run on 2026-10-01 with Copilot CLI 1.0.86 on macOS, using Copilot's own hosted model on an existing account, against Locus 0.1.0 from PyPI and our sample folder: the /mcp panel showed all five Locus tools, and Copilot answered which two documents disagree about a launch date, citing both files. This used Copilot's hosted model only. With a local Ollama model (COPILOT_OFFLINE) Copilot connected to Locus but returned empty answers in our runs, so local models are not verified yet.

OpenCodeConnectsNot yet verified

opencode.json with a local server type — opencode mcp list reported Locus connected (2026-09-19).

Last run 2026-09-19 · Linux (test sandbox) · Locus server with 3 tools (older version)

OpenCode supports local MCP servers through a project-level opencode.json file, with a server type of either "local" or "remote". Locus is a local stdio process, so it needs "local".

The top-level key is mcp, not mcpServers — and command is a single array of the executable plus its arguments, not separate command/args fields like every other platform on this page. Getting either of those wrong fails silently: OpenCode just reports "No MCP servers configured", no error. Confirmed 2026-09-19: opencode mcp list reported Locus ✓ connected.
JSON
{
  "mcp": {
    "locus": {
      "type": "local",
      "command": ["/absolute/path/to/locus", "serve"]
    }
  }
}

The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.

Codex✓ Works with

OpenAI's coding-agent CLI/IDE family — config.toml, not JSON. Not the ChatGPT chat app. Codex CLI 0.159.0 answered a test question citing two files (2026-10-01); the IDE extension and desktop panel are not tested yet.

Last run 2026-10-01 · macOS 26.3.1 · client version Codex CLI 0.159.0 · Locus 0.1.0 (5 tools)

"Codex" here means OpenAI's coding-agent product — the CLI, the ChatGPT desktop coding panel, and IDE extensions — not the general ChatGPT chat app, which is listed separately below under "Not yet supported." People mix these up constantly; check which one you actually have open.

Codex reads its MCP configuration from ~/.codex/config.toml, and that file is TOML, not JSON — path and format confirmed via Codex's own codex mcp add command (re-checked with codex-cli 0.156.1 on 2026-09-23). Checked 2026-09-20 with a real logged-in Codex session: codex mcp list/get only echo config, not proof of a live connection, so the real check was codex exec --json calling locus_list_sources — it returned a genuine tool- execution event whose error text ("Locus is not configured: LOCUS_EMBEDDER='local' needs an optional dependency...") only exists inside Locus's own embedder.py, proving real code executed through Codex's agent loop:

TOML
[mcp_servers.locus]
command = "/absolute/path/to/locus"
args = ["serve"]

The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.

Run on 2026-10-01 with Codex CLI 0.159.0 on macOS, signed in with a ChatGPT account (no API key), against Locus 0.1.0 from PyPI and our sample folder: Codex listed all five Locus tools as read-only, called locus_search, and answered which two documents disagree about a launch date, citing both files. That run covers the CLI only; the IDE extension and the desktop coding panel are not tested yet.

AntigravitySetup guideNot yet verified

Google's agent-first IDE — a config file or its /mcp manager; needs a signed-in session.

Not run with Locus by us yet: steps written from the vendor's docs.

Not tested by us with a saved record yet, so the steps below come from Google's own docs. Antigravity needs an interactive Google sign-in.

There are two ways to register Locus with Antigravity:

  1. Config file — edit ~/.gemini/config/mcp_config.json using the same mcpServers shape as Claude and Cursor above:
    JSON
    {
      "mcpServers": {
        "locus": {
          "command": "/absolute/path/to/locus",
          "args": ["serve"]
        }
      }
    }
    The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.
  2. Interactive manager — inside the tool, run the /mcp command and add Locus through its prompts instead of hand-editing JSON. This route is friendlier if you're less comfortable editing config files by hand.

Either way, a real signed-in Antigravity session is required before any tool call succeeds — the config alone isn't enough.

Gemini CLIConnectsNot yet verified

settings.json with the same mcpServers shape — gemini mcp list showed Locus connected in a trusted folder, no API key needed (2026-09-23).

Last run 2026-09-23 · Linux (test sandbox) · client version 0.60.0 · Locus 0.1.0 (5 tools)

~/.gemini/settings.json and this mcpServers shape are now confirmed correct (2026-09-19, via gemini mcp add -s user locus ..., which writes exactly this file). One real gotcha found running it: Gemini CLI's mcp add command defaults to -s project (writing to a project-local .gemini/settings.json next to whatever folder you're in), not user — pass -s user explicitly, or just hand-edit the global file below directly and skip the CLI command. Second gotcha: Gemini CLI disables every MCP server in a folder it doesn't trust yet, so gemini mcp list shows Locus as Disabled ("this folder is untrusted"). Trust the folder when Gemini CLI asks. On 2026-09-23 (Gemini CLI 0.60.0) gemini mcp list then showed Locus ✓ Connected with no API key. Chatting still needs an auth method (GEMINI_API_KEY or a Google sign-in).

Gemini CLI uses the same mcpServers JSON shape as Claude and Cursor, in ~/.gemini/settings.json:

JSON
{
  "mcpServers": {
    "locus": {
      "command": "/absolute/path/to/locus",
      "args": ["serve"]
    }
  }
}

The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.

OpenClawConnectsNot yet verified

Self-hosted, MIT-licensed (formerly Clawdbot) — a full CLI whose built-in probe listed all five Locus tools (2026-09-23).

Last run 2026-09-23 · Linux (test sandbox) · client version 2026.9.5 · Locus 0.1.0 (5 tools)

OpenClaw is not GUI-only: it ships a full headless CLI that probes the connection live before saving it.

Register and verify from a terminal:

Shell
openclaw mcp add locus \
  --command /absolute/path/to/locus \
  --arg serve
openclaw mcp probe locus --json

The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.

Re-run 2026-09-23 with OpenClaw 2026.9.5: probe listed all five Locus tools (locus__locus_search, locus__locus_list_sources, locus__locus_read_file, locus__locus_account_status, locus__locus_diagnose_connection) with zero diagnostics, no account or login needed. Current OpenClaw releases need Node 24.16 or newer. Older builds have no mcp command at all: on 2026-10-01 OpenClaw 2026.3.13 answered unknown command 'mcp', so update OpenClaw first if you see that. The Control UI (Settings → MCP → Add server) works too, if you'd rather not use the terminal.

otermConnectsNot yet verified

Ollama-specific terminal MCP client (pip install) — oterm's own MCP-loading code listed Locus's tools (2026-09-20).

Last run 2026-09-20 · Linux (test sandbox) · client version 0.24.0 · Locus server with 3 tools (older version)

oterm is a free, local-only terminal UI for Ollama, installed with pip install oterm (PyPI, confirmed real package, currently v0.24.0). It has no dedicated headless mcp list/mcp test subcommand — oterm itself is a full-screen Textual TUI app with no non-interactive mode — so it was verified by calling oterm's own MCP setup function (oterm.tools.mcp.setup.setup_mcp_servers) directly against a real locus.mcp_server, the same code path the TUI runs on startup, from an mcpServers block in oterm's config.json:

JSON
{
  "mcpServers": {
    "locus": {
      "command": "/absolute/path/to/locus",
      "args": ["serve"]
    }
  }
}

The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.

Confirmed 2026-09-20: a genuine stdio handshake returning the three tools the server had then, with their live descriptions:

Shell
>>> await setup_mcp_servers()
{'locus': [
  {'name': 'locus_search', 'description': "Semantic search over the user's locally indexed files. ..."},
  {'name': 'locus_list_sources', 'description': 'List files currently in the local index (paths only). ...'},
  {'name': 'locus_read_file', 'description': 'Read a bounded excerpt of ONE indexed file. Refuses paths that are not in the index.'}
]}
Config lives in oterm's data dir (~/.local/share/oterm/config.json by default, or $OTERM_DATA_DIR) — there is no per-project config file, and oterm has to be edited/restarted for MCP changes to take effect since servers are loaded once at startup.

Chinese-market coding agents

5 platforms
Kimi CLIConnectsNot yet verifiedBeing retired

Moonshot AI's original coding-agent CLI (pip install), which Moonshot is winding down in favour of Kimi Code CLI; its repository was archived on 2026-09-23 — kimi mcp test reported Locus connected (2026-09-20).

Last run 2026-09-20 · Linux (test sandbox) · Locus server with 3 tools (older version)

Being retired by its vendor. Moonshot AI says it will be wound down in favour of Kimi Code CLI, and archived its repository on 2026-09-23 (no further releases or fixes). It still installs and runs today. New setups: Kimi Code CLI, which has its own status on this page.

Kimi CLI (Moonshot AI's official coding-agent CLI — not the kimi.com chat app, which has no MCP support) is a Python tool, installed with pip install kimi-cli (not npm), with docs at moonshotai.github.io/kimi-cli. It reads MCP config from ~/.kimi/mcp.json, using the same mcpServers shape as every Claude-family client above — confirmed correct 2026-09-20, byte-for-byte, via Kimi CLI's own kimi mcp add command:

JSON
{
  "mcpServers": {
    "locus": {
      "command": "/absolute/path/to/locus",
      "args": ["serve"]
    }
  }
}

The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.

Or skip hand-editing JSON and run kimi mcp add locus -- /absolute/path/to/locus serve from a terminal. Kimi CLI ships a dedicated kimi mcp test <name> command that connects to the server and lists its tools — no login or model API key needed, since it's a pure MCP handshake. Confirmed 2026-09-20 (the server had three tools then):

Shell
$ kimi mcp test locus
Testing connection to 'locus'...
✓ Connected to 'locus'
  Available tools: 3
  Tools:
    - locus_search: Semantic search over the user's locally indexed...
    - locus_list_sources: List files currently in the local index (paths ...
    - locus_read_file: Read a bounded excerpt of ONE indexed file. Ref...

That handshake needs no account at all — but actually chatting with Kimi Code CLI does, since MCP and the model call are two separate steps. Get your own free key from Moonshot's console at platform.kimi.ai (API Keys page), then run /login inside Kimi Code CLI and pick Kimi Platform (API key) to paste it in — no config-file editing required. One honest caveat: Moonshot requires a small minimum recharge (around $1) before the API serves any request at all, so signup alone won't get you talking; a China-phone-registered account also gets an automatic ¥15 trial voucher that international signups are not confirmed to receive. Locus itself never sees this key — it lives entirely between Kimi Code CLI and Moonshot's API.

Kimi Code CLISetup guideNot yet verified

Moonshot AI's successor to Kimi CLI (npm @moonshot-ai/kimi-code) — documented from Moonshot's docs, not yet tested by us.

Not run with Locus by us yet: steps written from the vendor's docs.

Not tested with Locus yet. We installed it on 2026-09-20, but its device-code sign-in failed on Moonshot's side, so the test stopped before the MCP step. It also accepts a Moonshot API key. A successor does not inherit Kimi CLI's test result: it gets its own test before we say it works.

Install it from npm: npm install -g @moonshot-ai/kimi-code (MIT licence, Moonshot AI's MoonshotAI/kimi-code repository).

Moonshot's MCP docs (read 2026-10-02) say Kimi Code CLI reads MCP servers from ~/.kimi-code/mcp.json (all projects) or .kimi-code/mcp.json inside a project (the project file wins), in the same mcpServers shape as the clients above. The ~/.kimi/mcp.json file belongs to the older Kimi CLI. Inside the CLI, /mcp-config manages the list.

JSON
{
  "mcpServers": {
    "locus": {
      "command": "/absolute/path/to/locus",
      "args": ["serve"]
    }
  }
}
The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.

To chat, sign in with a Moonshot API key: create one in Moonshot's console at platform.kimi.ai (API Keys page), then run /login and pick the API-key option.

Qwen Code CLIConnectsNot yet verified

Alibaba's official open coding-agent CLI — qwen mcp list reported Locus connected (2026-09-19).

Last run 2026-09-19 · Linux (test sandbox) · Locus server with 3 tools (older version)

Qwen Code CLI (Alibaba's official open-source coding-agent CLI) uses the same mcpServers JSON shape as Claude and Cursor, in .qwen/settings.json (project) or ~/.qwen/settings.json (user-wide):

JSON
{
  "mcpServers": {
    "locus": {
      "command": "/absolute/path/to/locus",
      "args": ["serve"]
    }
  }
}

The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.

Or skip hand-editing JSON entirely and run qwen mcp add locus /absolute/path/to/locus serve from a terminal. One extra step: newly-added servers start pending approval — run qwen mcp approve locus once, then it connects on the next session. Confirmed 2026-09-19: qwen mcp list reported Locus ✓ Connected.

That MCP step needs no account — but a real chat turn does. Get your own free key by creating an Alibaba Cloud International account at bailian.console.alibabacloud.com (Model Studio), activating in the Singapore (International) region to trigger the free quota, then generating a key on the API-KEY page. Point Qwen Code CLI at it via its OpenAI-compatible env vars (OPENAI_API_KEY, OPENAI_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1, OPENAI_MODEL=qwen3-coder-plus) in .qwen/.env or ~/.qwen/settings.json's env block. Free quota is real but bounded per Alibaba's own docs: 1,000,000 tokens per eligible model, valid 90 days from activation, Singapore-region only — not indefinite. Locus itself never sees this key — it lives entirely between Qwen Code CLI and Alibaba's API.

DeepSeek Harness (dsh)ConnectsNot yet verified

DeepSeek's official open-source agent CLI — a real dsh session registered Locus's tools (2026-09-20); no API key needed for the MCP step itself.

Last run 2026-09-20 · Linux (test sandbox) · Locus server with 3 tools (older version)

Not the chat.deepseek.com app, which has no MCP config at all — this is DeepSeek's separate, official open-source agent CLI, package @deepseek-ai/dsh on npm (bin dsh). cordis.patch.yml is a top-level YAML array of patch entries that target an existing plugin by id; a bare {id, name, config} entry (or the old plugins: map shown previously) is read as "patch this existing id" and fails with patch: entry "…" not found if nothing with that id exists yet. To add a brand-new plugin instance — which an MCP server always is — wrap it in an insert list instead:

Current dsh releases (0.1.7 and later) already bundle the MCP client plugin, so there is nothing to install first. Do not run dsh plugin add @deepseek-ai/dsh-mcp-client: its npm latest tag points at an older build that dsh rejects as incompatible (checked 2026-09-29 on dsh 0.1.7-rc.2).

Add this to your profile's $DSH_HOME/profiles/<your-profile>/cordis.patch.yml:

YAML
- insert:
    - id: mcp-locus
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: locus
        transport: stdio
        command: /absolute/path/to/locus
        args: ['serve']

The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.

Tools then surface to the agent as mcp__locus__<tool_name>. Confirmed 2026-09-20: booting a profile with this patch (dsh --profile <name> "say hi") — with no DEEPSEEK_API_KEY set at all — still composes the plugin tree, connects to a real locus.mcp_server, and sends a real request whose tool list includes mcp__locus__locus_search, mcp__locus__locus_list_sources and mcp__locus__locus_read_file with descriptions matching the server's source exactly — recorded in dsh's own persisted session log. The MCP handshake is a local subprocess step that happens before any call to DeepSeek's API, so it needs no account; only actually chatting with the agent does.

To actually chat, get your own free key at platform.deepseek.com (a separate account from the chat.deepseek.com consumer app) — sign up, open API Keys, create one, and drop it in ~/.dsh/.env:

Shell
DEEPSEEK_API_KEY=sk-your-key-here

New accounts get a one-time 5-million-token grant (roughly $8–10 of usage), valid 30 days, claimable once — not an ongoing free tier. DeepSeek publishes no fixed requests-per-minute cap; it throttles dynamically under load instead of hard-rejecting. Locus itself never sees this key — it lives entirely between dsh and DeepSeek's API.

ZCode (GLM)Setup guideNot yet verified

Z.ai's free Electron desktop app for GLM — a GUI, not a CLI. Steps from Z.ai's docs; not yet tested by us.

Not run with Locus by us yet: steps written from the vendor's docs.

Not the ChatGLM/Z.ai chat app, and not open-source: ZCode is Z.ai's free, closed-source Electron desktop app. Only the underlying GLM model weights are open (MIT, on Hugging Face). Not yet tested by us with Locus, so the steps below come from Z.ai's docs. Packages named "zcode-cli" on npm or GitHub are unofficial third-party wrappers, not ZCode itself; install ZCode only from Z.ai.

Add Locus through Settings → MCP Servers in ZCode's UI (New MCP Server, or Import if you already have a Claude Code-style mcpServers config — ZCode can import that same JSON shape). ZCode also reads MCP config directly from disk: a user-level file under .zcode/cli/ and a workspace-level one directly under .zcode/, both editable by hand:

JSON
{
  "mcpServers": {
    "locus": {
      "command": "/absolute/path/to/locus",
      "args": ["serve"]
    }
  }
}
The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.

To check it connected: locus should show as enabled in Settings → MCP Servers. Then start a new chat and ask a question that needs more than one of your indexed files; a reply that cites real paths from your folder means it worked. If nothing happens, re-check the absolute path first.

Desktop apps & self-hosted platforms (not yet run by us)

7 platforms
LM StudioSetup guideNot yet verified

Free local-only desktop app — mcp.json with the same mcpServers shape as Claude Desktop, not yet tested by us.

Not run with Locus by us yet: steps written from the vendor's docs.

Not yet tested by us with Locus. The config shape below is corroborated across LM Studio's own docs and independent write-ups.
  1. Install LM Studio from lmstudio.ai (it runs on macOS, Windows and Linux, but Locus itself is not yet verified on Windows). No account needed — entirely local.
  2. In the app, switch to the Program tab in the right sidebar, then click Install → Edit mcp.json. This opens ~/.lmstudio/mcp.json (macOS/Linux) or %USERPROFILE%\.lmstudio\mcp.json (Windows, where Locus is not yet verified) in LM Studio's own editor.
  3. Add the same mcpServers shape used everywhere else on this page:
    JSON
    {
      "mcpServers": {
        "locus": {
          "command": "/absolute/path/to/locus",
          "args": ["serve"]
        }
      }
    }
    The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.
  4. Save — LM Studio auto-loads servers on save. Open a chat, click the plug icon near the message box, and confirm "locus" is listed with its tools enabled. Ask a multi-file question; when the model calls a Locus tool, LM Studio shows a confirmation dialog naming the tool before running it — approving it and getting a reply with real file paths is the actual proof this worked.
5ireSetup guideNot yet verified

Free, open-source cross-platform MCP client desktop app — configured through its Tools panel, not yet verified live.

Not run with Locus by us yet: steps written from the vendor's docs.

Not yet tested by us with Locus. 5ire's own docs don't fully spell out its on-disk config path, so the in-app form is the path to trust, not a hand-typed file location.
  1. Install 5ire (free, open-source — github.com/nanbingxyz/5ire) from its GitHub Releases page for your OS. Its Tools/MCP feature also expects Python, Node.js and uv to already be installed on your machine (5ire's own prerequisite, separate from however you installed Locus).
  2. In 5ire, go to Tools (right panel) → +Local to add a local (stdio) server. Fill in:
    • Command: /absolute/path/to/locus
    • Args: serve
    The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.
  3. Save, then switch the new locus entry's toggle ON — adding it isn't enough by itself. Expand it to confirm Locus's tools are listed (including locus_search, locus_list_sources and locus_read_file), then ask a multi-file question in chat and confirm the reply cites real paths.
Raycast AISetup guideNot yet verified

Mac-only, Raycast Pro required — native MCP support via its Manage MCP Servers command, not yet verified live.

Not run with Locus by us yet: steps written from the vendor's docs.

Mac-only, and MCP is a Raycast Pro feature (7-day free trial available) — not just a technical step, a real signup/paid gate to clear first. Not yet tested by us with Locus.
  1. Install Raycast from raycast.com, sign in, and start the Pro trial (required before MCP will work at all).
  2. Open Raycast (⌥ Space), search for Install MCP Server (or use Manage MCP Servers → Install New Server). Fill in: Name locus, Transport stdio, Command /absolute/path/to/locus, Arguments serve. The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.
  3. Press ⌘↵. Raycast saves the config, connects, and pulls in the tool list automatically — success here is itself the confirmation. To use it: invoke Raycast AI and prefix your message with @mcp, then ask a multi-file question and confirm the reply cites real file paths.

All servers configured this way live in one mcp-config.json file inside Raycast's extension support directory — find it via Manage MCP Servers → Show Config File in Finder rather than typing a path by hand.

Kilo CodeSetup guideNot yet verified

Roo Code's actively-maintained fork (now under Anaconda) — legitimacy confirmed, config shape not yet click-tested against Locus.

Not run with Locus by us yet: steps written from the vendor's docs.

Real, currently-maintained project — MIT-licensed, ~20-25k GitHub stars, acquired by Anaconda (2026-07-15, confirmed via Anaconda's own press release plus independent coverage), genuinely supports MCP servers. It started as a fork of Roo Code, and its own migration tooling can copy an existing .roo/mcp.json straight across. Two config generations exist, and picking the wrong one silently fails — check which one you have before pasting either (last step below).

Generation 1 (legacy, inherited from Roo) — project file .kilocode/mcp.json:

JSON
{
  "mcpServers": {
    "locus": {
      "command": "/absolute/path/to/locus",
      "args": ["serve"]
    }
  }
}

Generation 2 (current, rebuilt on Kilo's shared "OpenCode server" engine) — a different key, shape and file: kilo.jsonc (project or ~/.config/kilo/kilo.jsonc):

JSON
{
  "mcp": {
    "locus": {
      "type": "local",
      "command": ["/absolute/path/to/locus", "serve"],
      "enabled": true
    }
  }
}

To tell which generation you have, open the extension's MCP settings (one reported path: Settings → Agent Behaviour → MCP Servers) and use its Add Server form. Or create .kilocode/mcp.json with the Generation 1 shape and watch the extension's output log: a parse or "unrecognized key" warning means you have Generation 2, so use kilo.jsonc instead.

The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.

Former Roo Code users: Roo Code's VS Code extension shut down on 2026-05-15. Its team pointed users to Cline (the project Roo Code forked from) or Kilo Code, which can copy an existing .roo/mcp.json across.

Open WebUISetup guideNot yet verified

Self-hosted, Docker — needs the official mcpo proxy bridge (stdio isn't supported directly, and native MCP Streamable HTTP has an open, unresolved bug), not yet verified live.

Not run with Locus by us yet: steps written from the vendor's docs.

Locus only speaks stdio by default, and Open WebUI doesn't spawn arbitrary local commands itself — it needs a bridge. Open WebUI does have a newer native "MCP (Streamable HTTP)" option (and Locus does have an opt-in locus serve --transport streamable-http mode that could feed it directly), but an open GitHub discussion (open-webui/open-webui#14776) reports Open WebUI sending a spec-incompatible request against multiple unrelated MCP servers, failing the handshake — no fix confirmed when we checked. Use mcpo (Open WebUI's own official MCP-to-OpenAPI proxy) first.

Start Open WebUI (official quick-start command):

Shell
docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:main

On your host (not inside that container), runmcpo in front of Locus:

Shell
uvx mcpo --port 8000 --api-key "<pick-any-secret-string>" \
  -- /absolute/path/to/locus serve
The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.

Verify mcpo itself first: open http://localhost:8000/docs and confirm it lists Locus's tools. Then in Open WebUI, go to ⚙️ Settings → Integrations (or Admin Panel → Settings → Integrations for a shared install) → + Add Connection, and enter URL http://host.docker.internal:8000 (reachable thanks to the --add-host flag above) with the same API key you passed to mcpo.

Confirm: the tool server shows connected/healthy in Integrations. In a chat, click the tools/wrench icon below the message box and enable it for that chat (tools are opt-in per chat, not always-on) — a reply citing real file paths confirms the full round trip.

AnythingLLMSetup guideNot yet verified

Self-hosted, Docker — use Locus's own streamable-http mode to sidestep a real, documented container/stdio bug, not yet verified live.

Not run with Locus by us yet: steps written from the vendor's docs.

A stdio server has to be spawned inside AnythingLLM's own container, so a plain /absolute/path/to/locus command won't resolve there by default — a real, open GitHub issue (Mintplex-Labs/anything-llm#4085) documents exactly this failure mode ("spawn docker ENOENT") for a different stdio-style server. Route around it: run locus serve --transport streamable-http on your host and point AnythingLLM at it by URL instead of by command.

Start AnythingLLM:

Shell
docker run -d -p 3001:3001 \
  -v /opt/anythingllm/storage:/app/server/storage \
  -e STORAGE_LOCATION=/app/server/storage \
  --name anythingllm \
  mintplexlabs/anythingllm

On your host, add a token and start Locus in HTTP mode. Locus reads a .env file from the folder you start it in, so use one folder for this:

Shell
mkdir -p ~/locus-http && cd ~/locus-http
echo "LOCUS_MCP_TOKEN=$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')" >> .env
locus serve --transport streamable-http --host 0.0.0.0 --port 8001

Open Agent Skills in the AnythingLLM UI once (this creates its config file), then edit plugins/anythingllm_mcp_servers.json under the storage directory you mounted above:

JSON
{
  "mcpServers": {
    "locus": {
      "type": "streamable",
      "url": "http://host.docker.internal:8001/mcp",
      "headers": {
        "Authorization": "Bearer <the LOCUS_MCP_TOKEN value from your .env>"
      }
    }
  }
}

Confirm: the locus entry on the Agent Skills page shows RUNNING (green), not STOPPED. In a workspace chat, invoke @agent and ask a multi-file question — a reply citing real file paths confirms the full round trip.

Goose (Block / Agentic AI Foundation)ConnectsNot yet verified

Goose 1.52.0 loaded all five Locus tools with a local Ollama model (2026-10-01). A cited answer is not yet recorded by us.

Last run 2026-10-01 · macOS 26.3.1 · client version 1.52.0 · Locus 0.1.0 (5 tools)

The tools load — in our test on 2026-10-01 with Goose 1.52.0 and a local Ollama model (qwen3:8b), the request Goose sent to the model carried all five Locus tools. A cited answer is not yet recorded by us: in that run the model returned no answer to our test question. Goose will not run a chat turn without a configured LLM provider; the last step below sets up a free local one.
  1. Install: curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash
  2. Add Locus to ~/.config/goose/config.yaml (macOS/Linux) — the exact shape that loaded in our 2026-09-21 run:
    YAML
    extensions:
      locus:
        type: stdio
        cmd: /absolute/path/to/locus
        args: ["serve"]
        enabled: true
        timeout: 300
    The important, easy-to-miss detail: command has to be the full, absolute path to the locus command — not just locus, because desktop apps don't see your terminal's PATH. To get it, run command -v locus in a terminal and paste what it prints. After a uv tool or pipx install it is usually ~/.local/bin/locus written out in full, such as /Users/you/.local/bin/locus on macOS or /home/you/.local/bin/locus on Linux. Running Locus from a source checkout instead (developers)? Use the checkout's own .venv/bin/locus as the command, written out in full (run pwd inside the checkout and add /.venv/bin/locus), with the same serve argument.
  3. Run goose doctor and look for "Setting MCP process working directory" followed by ✓ extensions ready — that's the confirmed-working half.
  4. To go further: install Ollama, ollama pull llama3.2, then goose configure → Configure Providers → Ollama → confirm host localhost:11434 → pick your model. Then goose session --with-extension "/absolute/path/to/locus serve" and ask it to use a tool — the transcript naming locus_search and a reply citing real file paths is the missing, final proof.

Web AI apps (through the hosted relay)

4 platforms
Claude.ai (web app)✓ Works with

Works with Locus through its hosted relay, with cited answers, connecting with OAuth sign-in. In our 2026-10-04 run Claude.ai chose Locus by itself in 3 of 3 new chats; it asks your permission for each Locus call.

Last run 2026-10-04 · macOS, through the hosted relay · client version claude.ai web · Locus 0.1.3 (PyPI)

In our test on 2026-10-04, with seventeen connectors switched on, Claude.ai chose Locus by itself in 3 of 3 new chats for a question about the test files, then answered correctly and cited the files. It asks your permission before each Locus call, about four per question: choose Allow once, or Always allow if you accept that. On 2026-10-02, on an earlier version of Locus, the same app did not call Locus until we asked it to; if yours answers without calling Locus, ask it to use Locus, switch off connectors you do not need in that chat, and give the connector a clear name such as "Locus - my files". We have not run the full lifecycle (editing and deleting files, the computer going offline), so it is marked Works with, not Works with: full lifecycle.
  1. On the computer that holds your index, install Locus with its relay extra (uv tool install --python 3.12 "locusfiles[relay]", or pipx install "locusfiles[relay]"; if you index with on-device embeddings, use "locusfiles[local,relay]" instead) and index a folder, as in the managed quickstart. The relay serves the index you made, so start it with the same LOCUS_EMBEDDER (managed for a Locus plan), and the same LOCUS_COLLECTION and LOCUS_DATA_DIR if you set them: an index holds one embedding model. The web connectors need a Locus plan or trial and an API key (how to create one: API keys).

    In a terminal on that computer, first enter your Locus API key (paste it and press Enter; nothing is shown):

    Shell
    read -rs LOCUS_API_KEY

    Then run these lines one after another:

    Shell
    export LOCUS_API_KEY
    export LOCUS_EMBEDDER=managed
    export LOCUS_MCP_RELAY_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImRtdHlicXRxdm5hZ3djZmZodXpyIiwicm9sZSI6ImFub24iLCJpYXQiOjE3ODk1NTYzMTgsImV4cCI6MjEwNTEzMjMxOH0.4MxlNEmBZXrmSQxoHBnFyjsFqqYIsZz1eZP4vdWgXzs
    locus serve --transport relay

    The LOCUS_MCP_RELAY_SUPABASE_ANON_KEY line is Locus's public relay key. It is not a secret: it is the same public value this website sends to every browser, and what you can reach through the relay is decided by your account, not by this key. Locus 0.1.3 and later fetch it from the relay themselves, so there you can leave the line out. With an older Locus the line is required: without it the command stops with "LOCUS_MCP_RELAY_SUPABASE_ANON_KEY is not set". To see which version you have, run uv tool list (or pipx list).

    Leave it running, with the computer on and awake: the assistant can only reach Locus while it is. If the command stopped because the computer slept or lost the network, run it again; if the first answer times out, ask again.
  2. In Claude.ai open Settings → Connectors and add a custom connector with the URL https://locusfiles.com/api/mcp/relay. Leave any advanced OAuth fields empty.
  3. Press Connect, sign in to Locus, choose which of your computers it may search, and approve.
  4. In a new chat, switch the connector on and ask about your files. You can disconnect it at any time on your Locus account's connected-assistants page.

What this sends: When you reach your computer from another device or a web AI app, your question and the matching excerpts travel through Locus's relay (Vercel and Supabase) to and from your computer. They are encrypted in transit and we don't store them. Through the relay, your AI app can read a whole file piece by piece (up to 40,000 characters per read), list the paths of your indexed files, and, when it asks, see your account status (plan, trial end, usage, number of API keys) and setup details (operating system, Python and Locus versions, embedder, number of indexed chunks).

Only one computer per account serves remote requests at a time; starting Locus relay on another computer takes over. The computer must be on, awake and running Locus. Remote connection needs an active subscription or trial.

The assistant signs in with OAuth: you approve it on a Locus consent screen and it keeps its own sign-in token, not your Locus API key. Your key stays on the computer that runs Locus. Anyone who holds your Locus API key can search and read your indexed files through the relay while your computer is serving, take over as your relay computer, spend your managed-embedding budget, and act as your account for up to ten minutes with each relay token they get from it. Keep it secret. If it leaks, revoke it from the dashboard, then check your key list again after ten minutes and revoke any key you did not create. To cut the assistant off, choose Disconnect next to it under Connected assistants; revoking API keys does not disconnect it.

ChatGPT (general chat, not Codex)✓ Works with

Works with Locus on a paid plan through its hosted relay, with cited answers, connecting with OAuth sign-in. We did not try the free plan.

Last run 2026-10-04 · macOS, through the hosted relay · client version chatgpt.com web · plan a paid plan; the free plan was not tested · Locus 0.1.3 (PyPI)

ChatGPT's web app can't start a program on your computer, so it reaches Locus through Locus's hosted relay: the computer that holds your index runs Locus, and ChatGPT connects to the relay with a custom MCP server that signs in with OAuth. We tested this on 2026-10-02 on the ChatGPT website, on a paid plan, with a Locus account of our own. With the Locus connector on in the chat, ChatGPT answered questions about a sample folder with the file paths it came from, and called Locus for both questions without being told to. We did not test the free plan, so we do not say it works there. We have not run the full lifecycle (editing and deleting files, disconnecting, the computer going offline, removal) and we did not test the ChatGPT phone or desktop apps, so it is marked Works with, not Works with: full lifecycle.

  1. On the computer that holds your index, install Locus with its relay extra (uv tool install --python 3.12 "locusfiles[relay]", or pipx install "locusfiles[relay]"; if you index with on-device embeddings, use "locusfiles[local,relay]" instead) and index a folder, as in the managed quickstart. The relay serves the index you made, so start it with the same LOCUS_EMBEDDER (managed for a Locus plan), and the same LOCUS_COLLECTION and LOCUS_DATA_DIR if you set them: an index holds one embedding model. The web connectors need a Locus plan or trial and an API key (how to create one: API keys).

    In a terminal on that computer, first enter your Locus API key (paste it and press Enter; nothing is shown):

    Shell
    read -rs LOCUS_API_KEY

    Then run these lines one after another:

    Shell
    export LOCUS_API_KEY
    export LOCUS_EMBEDDER=managed
    export LOCUS_MCP_RELAY_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImRtdHlicXRxdm5hZ3djZmZodXpyIiwicm9sZSI6ImFub24iLCJpYXQiOjE3ODk1NTYzMTgsImV4cCI6MjEwNTEzMjMxOH0.4MxlNEmBZXrmSQxoHBnFyjsFqqYIsZz1eZP4vdWgXzs
    locus serve --transport relay

    The LOCUS_MCP_RELAY_SUPABASE_ANON_KEY line is Locus's public relay key. It is not a secret: it is the same public value this website sends to every browser, and what you can reach through the relay is decided by your account, not by this key. Locus 0.1.3 and later fetch it from the relay themselves, so there you can leave the line out. With an older Locus the line is required: without it the command stops with "LOCUS_MCP_RELAY_SUPABASE_ANON_KEY is not set". To see which version you have, run uv tool list (or pipx list).

    Leave it running, with the computer on and awake: the assistant can only reach Locus while it is. If the command stopped because the computer slept or lost the network, run it again; if the first answer times out, ask again.
  2. In ChatGPT open Settings → Plugins, press + and choose to create a custom MCP server (in our French test it read "Créer un serveur MCP personnalisé"). Name it Locus, set the URL to https://locusfiles.com/api/mcp/relay and keep authentication on OAuth, the default.
  3. ChatGPT shows a warning about custom servers with a checkbox to confirm you trust the server (in the French UI we tested: "Je comprends et souhaite continuer"; the English label may differ). Read it, and tick the box if you want to go on.
  4. When ChatGPT asks to connect Locus, continue to Locus, sign in if it asks, check the consent screen, then Approve.
  5. Start a chat and switch the Locus connector on for it (we attached it from the + menu in the message box), then ask about your own files. ChatGPT should call locus_search and cite the file paths in its answer.

Menu names vary by language and by ChatGPT version. Older versions show custom connectors under Settings → Apps → Advanced settings, behind a Developer mode switch; we have not tested that route. In our test an answer took 15 to 19 seconds.

What this sends: When you reach your computer from another device or a web AI app, your question and the matching excerpts travel through Locus's relay (Vercel and Supabase) to and from your computer. They are encrypted in transit and we don't store them. Through the relay, your AI app can read a whole file piece by piece (up to 40,000 characters per read), list the paths of your indexed files, and, when it asks, see your account status (plan, trial end, usage, number of API keys) and setup details (operating system, Python and Locus versions, embedder, number of indexed chunks).

Only one computer per account serves remote requests at a time; starting Locus relay on another computer takes over. The computer must be on, awake and running Locus. Remote connection needs an active subscription or trial.

The assistant signs in with OAuth: you approve it on a Locus consent screen and it keeps its own sign-in token, not your Locus API key. Your key stays on the computer that runs Locus. Anyone who holds your Locus API key can search and read your indexed files through the relay while your computer is serving, take over as your relay computer, spend your managed-embedding budget, and act as your account for up to ten minutes with each relay token they get from it. Keep it secret. If it leaks, revoke it from the dashboard, then check your key list again after ten minutes and revoke any key you did not create. To cut the assistant off, choose Disconnect next to it under Connected assistants; revoking API keys does not disconnect it.

Gemini Enterprise (Business Edition)Setup guideNot yet verified

Google's business tier lets an admin add a custom MCP server with OAuth; documented, not tested by us.

Not run with Locus by us yet: steps written from the vendor's docs.

Researched 2026-10-02 from Google's help pages: in Gemini Enterprise, Business edition, an admin adds a server under Settings & help → Manage team → Connected apps → Add MCP Server (other editions use a Google Cloud console route). Google lists only OAuth 2.0 with a client the admin registers by hand, or no authentication; there is no header option, so a Locus API key cannot be pasted there. The server must speak Streamable HTTP (the older SSE transport isn't accepted) over a publicly trusted TLS certificate.

We have not tested this. Each organization would need its own registered OAuth client for Locus, so it is an organization setup we do with you, not a paste-a-URL step. The personal Gemini app is a separate product: Google describes custom apps there only for some eligible US accounts, and we have not tested that either.

Microsoft Copilot (via Copilot Studio)Setup guideNot yet verified

Enterprise-only, via a custom connector an org's own IT builds in Copilot Studio — not a paste-a-URL flow like ChatGPT's.

Not run with Locus by us yet: steps written from the vendor's docs.

Researched 2026-09-21: Microsoft 365 Copilot doesn't take a direct MCP connector URL from an end user. An organization's own Copilot Studio admin builds a custom connector (a YAML schema wrapping our MCP server's URL, authenticated with a Locus API key tied to that org's subscription) and adds it to their agents — reached public preview 2026-05-18, still maturing. Real, buildable on the same relay backend, but a heavier per-organization setup than Claude.ai/ ChatGPT's connector UI, not a universal one-time build.

Troubleshooting

  • If any client shows Locus as disconnected, the almost-always cause is the command path: it must be the absolute path that command -v locus prints (or, from a source checkout, the checkout's full .venv/bin/locuspath), not a bare locus or a relative path, with serve as its argument. Also make sure locus index has been run at least once — an empty index still connects fine, it just has nothing to search yet.
  • On GitHub Copilot specifically: double-check you used servers as the top-level JSON key in .vscode/mcp.json, not mcpServers. Every other platform on this page uses mcpServers — Copilot is the one exception, and pasting the wrong key silently does nothing.
  • On Codex specifically: ~/.codex/config.toml is TOML, not JSON. Don't copy one of the JSON { "mcpServers": ... } examples from elsewhere on this page into it — use the [mcp_servers.locus] TOML block shown in the Codex section above, or the file won't parse.