Multi-Instance Litmus Edge

6 min

Multi-Instance Litmus Edge

The Web UI lets you register multiple Litmus Edge devices from a single MCP server and switch the active one without restarting.

Why

A single MCP server is often shared across more than one physical edge: a lab unit, a staging deployment, a production deployment, a customer demo box. Multi-instance support keeps each set of credentials on file and lets you flip between them from the chat header.

Where it lives

Instances are stored in the .env file under indexed keys:

EDGE_INSTANCE_1_URL=https://10.0.0.10
EDGE_INSTANCE_1_CLIENT_ID=...
EDGE_INSTANCE_1_CLIENT_SECRET=...
EDGE_INSTANCE_1_NAME=Lab

EDGE_INSTANCE_2_URL=https://10.0.0.20
EDGE_INSTANCE_2_CLIENT_ID=...
EDGE_INSTANCE_2_CLIENT_SECRET=...
EDGE_INSTANCE_2_NAME=Staging

ACTIVE_EDGE_INSTANCE=1

The active instance's credentials are mirrored into the canonical keys:

EDGE_URL=...
EDGE_API_CLIENT_ID=...
EDGE_API_CLIENT_SECRET=...

So every tool and every external MCP client continues to see a single set of EDGE_URL / EDGE_API_CLIENT_ID / EDGE_API_CLIENT_SECRET headers, regardless of how many instances you have configured.

Managing instances from the Web UI

/update-env -> Litmus Edge Instances:

Add a new instance: provide URL, client ID, client secret, optional friendly name.

List registered instances. The current active one is highlighted.

Switch the active instance. The MCPClient is rebuilt server-side so subsequent tool calls use the new credentials immediately.

Remove an instance. If the active one is removed, the next available instance becomes active.

Managing instances from the API

Endpoint	Method	Purpose
/api/edge-instances	GET	List all registered instances.
/api/add-edge-instance	POST	Append a new instance.
/api/remove-edge-instance	POST	Remove an instance by index.
/api/switch-edge-instance	POST	Set a different instance as active.
/api/edge-health?index=N	GET	Check a specific instance without switching the active one.

Health page

/health shows one status card per configured instance. Each card calls /api/edge-health?index=N so you can verify all your edges from one place without disturbing the active one.

External MCP clients and multi-instance

External clients (Claude Desktop, Cursor, etc.) connect to the SSE endpoint directly and supply their own headers. They are not aware of the Web UI's instance list. If you want different clients to talk to different edges, run separate MCP server containers or send different headers per client.

The instance list is only consumed by the Web UI's chat at http://localhost:9000.