Connect an MCP client

Start with server setup and pairing. This page describes how Lomi registers itself in an external client. Registering a server and approving its session are separate steps.

Automatic registration

Open Settings > Agent control > Connect an agent, choose your CLI and select Add Lomi to …. The picker shows supported executables discovered in your default local shell environment; configuration files alone do not count as an installed CLI. Use Refresh after installing or removing a client.

The action registers a user-level server named lomi and starts the MCP server for the current Lomi session. It does not restart the CLI. All client configurations > Set up all eligible clients registers the clients currently eligible for setup.

Client	Executable	Default user configuration	Shape
Claude Code	claude	~/.claude.json	mcpServers.lomi
Codex	codex	~/.codex/config.toml	[mcp_servers.lomi]
Gemini CLI	gemini	~/.gemini/settings.json	mcpServers.lomi
GitHub Copilot CLI	copilot	~/.copilot/mcp-config.json	mcpServers.lomi, local type and tools list
Cursor CLI	cursor-agent	~/.cursor/mcp.json	mcpServers.lomi
OpenCode	opencode	~/.config/opencode/opencode.json or .jsonc	v2 mcp.servers.lomi, command array
OpenClaw	openclaw	~/.openclaw/openclaw.json	JSON5 mcp.servers.lomi
Hermes Agent	hermes	~/.hermes/config.yaml	mcp_servers.lomi
Kilo Code CLI	kilo, kilocode	~/.config/kilo/kilo.jsonc	mcp.lomi, command array
Qwen Code	qwen	~/.qwen/settings.json	mcpServers.lomi
Kiro CLI	kiro-cli	~/.kiro/settings/mcp.json	mcpServers.lomi
Mistral Vibe	vibe	~/.vibe/config.toml	[[mcp_servers]], name = "lomi", stdio
Kimi Code CLI	kimi	~/.kimi-code/mcp.json	mcpServers.lomi
Grok Build	grok	~/.grok/config.toml	[mcp_servers.lomi]
Antigravity CLI	agy	~/.gemini/config/mcp_config.json	mcpServers.lomi, local command/args

These are the 15 clients in the Settings picker, not a claim that every adapter in source or every desktop variant is offered there. Status-bar suggestions for verified running local processes have their own capability checks. The source CLI matrix documents additional adapters and manual-only clients.

What is written

Automatic setup uses the actual Lomi executable and this argument pattern:

--mcp --discovery-file <absolute-app-data>/agent-control/discovery.json --discovery-key <pinned-public-key>

The public key verifies a signed descriptor containing the running instance’s endpoint and broker certificate fingerprint. The registration survives a server/app restart; permission approval does not. After restart, reconnect the client and pair again with YOLO off. Moving the executable or replacing its app-data identity requires a new registration.

Lomi checks the configuration revision, backs up its exact original bytes and publishes the replacement atomically. It preserves unrelated settings and refuses to overwrite another server already named lomi. JSON/JSONC/JSON5 edits preserve unrelated text and comments. YAML edits reformat the document and remove comments; the original is retained in the backup. Unsupported aliases, merge keys, tags or duplicate keys block the YAML update.

Custom profiles

Settings uses the current user’s configuration environment. A status-bar installation uses the detected running CLI’s environment and configuration location. Relevant overrides for the picker include CODEX_HOME, GEMINI_CLI_HOME, COPILOT_HOME, XDG_CONFIG_HOME, OPENCODE_CONFIG, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, HERMES_HOME, KILO_CONFIG, QWEN_HOME, KIRO_HOME, VIBE_HOME, KIMI_CODE_HOME and GROK_HOME. GEMINI_CLI_HOME is the parent of .gemini; path overrides must resolve to absolute locations.

Use the client’s own setup when Lomi reports ambiguous or additional configuration:

• OpenCode with both JSON and JSONC files, an inline configuration or an extra config directory; legacy OpenCode maps need v2 migration.
• Kilo with inline configuration or an extra config directory.
• OpenClaw with a custom profile/home.
• Claude with a custom CLAUDE_CONFIG_DIR MCP registry.
• Vibe with VIBE_CLI=rust; Lomi’s automatic stdio adapter targets the Python CLI.

Antigravity also supports workspace-local .agents/mcp_config.json; Lomi registers its global file. In the reviewed working tree, an empty/JSON-whitespace-only Antigravity file is initialized only after an installation click, with an exact backup. Other malformed JSON remains intact. A remote serverUrl entry is not a local Lomi registration. The source audit identifies these local adapter changes.

Manual configuration

Use Preferences > Manual configuration > MCP JSON configuration for this running instance. Start the server first and select Copy configuration.

This route needs the optional standalone lomi-mcp executable next to the application’s executable. A source build can create it with:

cargo build --manifest-path src-tauri/Cargo.toml --locked -p lomi-mcp

The copied JSON has this structure. Replace every placeholder with values from your running instance; these examples are not working endpoints:

{
  "mcpServers": {
    "lomi": {
      "command": "/absolute/path/to/lomi-mcp",
      "args": [
        "--endpoint", "/private/current-instance/control.sock",
        "--instance", "CURRENT_INSTANCE_ID",
        "--broker-sha256", "CURRENT_BROKER_CERTIFICATE_SHA256"
      ]
    }
  }
}

Adapt the client’s root key and local-server format. For a TOML client using mcp_servers, the equivalent connection values are:

[mcp_servers.lomi]
command = "/absolute/path/to/lomi-mcp"
args = ["--endpoint", "/private/current-instance/control.sock", "--instance", "CURRENT_INSTANCE_ID", "--broker-sha256", "CURRENT_BROKER_CERTIFICATE_SHA256"]

Copy this configuration again after each server restart. The direct endpoint, instance ID and certificate fingerprint belong to that instance. Automatic signed discovery is the persistent alternative.

Any compatible stdio client can use the copied values in its supported format. A client that only supports remote HTTP servers cannot connect directly to Lomi’s stdio endpoint. Pi requires an MCP extension; Aider and official SWE-agent do not gain native MCP support by adding an invented config entry. The Settings picker does not automatically register Claude Desktop or other unlisted desktop apps.

Client approvals

Your MCP host can require its own tool approval. Lomi pairing and operation approvals do not bypass that policy. If a modifying call never reaches Lomi, inspect the client’s tool policy and interactive approval flow. Conversely, approving a tool in the client does not grant a missing Lomi scope.

The application has no general settings page for adding arbitrary third-party MCP servers to Chat AI. Its native Chat integration exposes the shared Lomi catalog described in architecture.

Source: CLI catalog, configuration adapters, signed discovery. Uncommitted adapter differences are recorded in the audit.