Connect Locus to your AI assistant

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 pipx or uv tool 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.

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

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 pipx or uv tool 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.

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 pipx or uv tool 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 5 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.

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. Find the MCP settings panel — previously Windsurf Settings → Cascade → MCP Servers. Since the rename, the exact menu path may have shifted; look for an equivalent "MCP Servers" entry under settings and verify locally before assuming this path still matches.
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 pipx or uv tool 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 five tools, including locus_search, locus_list_sources and locus_read_file.

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 pipx or uv tool 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 five 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.

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

{
  "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 pipx or uv tool 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).

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:

copilot mcp add locus -- /absolute/path/to/locus serve
copilot mcp list   # or: copilot mcp get locus

Confirmed 2026-09-21 on the founder's own machine: 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. Earlier sign-in failures in a sandboxed test environment (403 "sessions are bound to their configured repositories") were specific to that sandbox; a normal interactive login worked first time.

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".

{
  "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 pipx or uv tool 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 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:

[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 pipx or uv tool 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.

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 pipx or uv tool 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 CLI uses the same mcpServers JSON shape as Claude and Cursor, in ~/.gemini/settings.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 pipx or uv tool 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.

Register and verify from a terminal:

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 pipx or uv tool 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. The Control UI (Settings → MCP → Add server) works too, if you'd rather not use the terminal.

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:

{
  "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 pipx or uv tool 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:

>>> 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.'}
]}

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:

{
  "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 pipx or uv tool 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):

$ 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.

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

Moonshot's MCP docs describe adding servers with a kimi mcp add command, using the stdio transport for a local server like Locus. Give it the name locus, the command /absolute/path/to/locus and the argument serve. Check kimi mcp add --help for the exact argument order in your version.

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 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):

{
  "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 pipx or uv tool 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.

First install the MCP client plugin into your profile (once):

dsh plugin --profile <your-profile> add @deepseek-ai/dsh-mcp-client

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

- 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 pipx or uv tool 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:

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.

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:

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

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.

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 pipx or uv tool 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.

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 pipx or uv tool 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 all 5 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.

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 pipx or uv tool 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.

Generation 1 (legacy, inherited from Roo) — project file .kilocode/mcp.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):

{
  "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.

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.

Start Open WebUI (official quick-start command):

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:

uvx mcpo --port 8000 --api-key "<pick-any-secret-string>" \
  -- /absolute/path/to/locus serve

Verify mcpo itself first: open http://localhost:8000/docs and confirm it lists Locus's 5 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.

Start AnythingLLM:

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:

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:

{
  "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.

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 pipx or uv tool 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.

Not available yet. The web app at claude.ai can't reach a program on your computer directly, so it needs Locus's hosted relay. On individual Claude plans, custom connectors sign in with OAuth. The relay accepts only a Locus API key today, so there are no working setup steps to show yet. Sign-in support is being built; this entry will get real steps once we have tested them.

Until then, use Claude Desktop or Claude Code, which connect to Locus on your own computer. When remote connection ships, this entry will also say exactly what passes through the relay, as the ChatGPT entry below does.

Updated 2026-09-21: ChatGPT's Developer Mode connectors need a public HTTPS endpoint — Locus now has one, its hosted relay at /api/mcp/relay. Deployed and responding to the MCP protocol; a real end-to-end handshake through ChatGPT's own connector UI hasn't been confirmed yet.

Researched 2026-09-21: custom MCP server connections exist only in Gemini Enterprise / Business Edition (admin-configured, under Gemini Spark → Connected Apps) — the free personal Gemini web/app has no equivalent today, and that's Google's own product decision, not something we can build around.

Requirements, per Google's own docs: the connector must speak the Streamable HTTP transport specifically (the older SSE transport isn't accepted), a publicly-trusted TLS certificate (no self-signed certs), and OAuth 2.0. Our relay endpoint isn't confirmed to satisfy the full Streamable HTTP transport spec (session IDs, SSE-optional response mode) yet — that's the concrete next step before this can be tested, not assumed to already work.

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.