# What Is Combo Switching in OmniRoute? A Complete Guide to Activating and Deactivating Model Chains

> Learn combo switching in OmniRoute to activate and deactivate model chains using the omiroute_switch_combo tool or API. Master your routing engine efficiently.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: deep-dive
- Published: 2026-08-01

---

**Combo switching in OmniRoute is the mechanism for toggling a model chain's participation in the routing engine by setting its `isActive` flag to `true` (active) or `false` (inactive) via the `omniroute_switch_combo` MCP tool or direct API calls.**

In OmniRoute, a **combo** is a configurable chain of AI models bundled with a routing strategy—such as priority-based, weighted, or round-robin selection. Combo switching gives operators fine-grained control over which chains are eligible to handle incoming requests without deleting their configuration. According to the OmniRoute source code, this is implemented through a simple boolean flag that the resolver checks before selecting a target combo.

## How Combo Switching Works Internally

The combo switching flow involves three coordinated layers: the MCP tool interface, the REST API, and the database persistence layer.

### MCP Tool: `omniroute_switch_combo`

The primary interface for combo switching is the MCP tool registered in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts). This tool requires the `write:combos` scope and accepts two parameters:

- `comboId`: The unique identifier of the target combo
- `active`: Boolean indicating the desired state

When invoked, the tool handler (`handleSwitchCombo` at lines 75–89) constructs a `PUT` request to `/api/combos/:id` with the JSON body `{ "isActive": <true|false> }`.

### API Route and Database Update

The route handler in `src/app/api/combos/[id]/route.ts` (lines 101–119) validates the incoming request and delegates persistence to `updateCombo` in [`src/lib/db/combos.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/combos.ts). This function executes a SQL update against the SQLite `combos` table:

```typescript
// From src/lib/db/combos.ts, lines 99-106
export async function updateCombo(id: string, updates: Partial<Combo>) {
  const { isActive, ...otherFields } = updates;
  // SQLite update with parameterized query
  return db.prepare(`
    UPDATE combos 
    SET isActive = ?, updatedAt = datetime('now')
    WHERE id = ?
  `).run(isActive, id);
}

```

After the database update, the combo cache is invalidated and a log entry is recorded via `logToolCall` to maintain an audit trail of activation changes.

### Router Resolution

The critical enforcement point occurs in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts), where the combo resolver filters candidates based on `isActive`. An inactive combo is excluded from consideration entirely, regardless of its routing strategy configuration or model availability.

## Methods for Switching Combos

You can activate or deactivate combos through three interfaces depending on your operational context.

### Method 1: MCP Client (JavaScript/TypeScript)

Direct API calls using standard fetch:

```javascript
// Activate a combo
await fetch("/api/combos/123e4567-e89b-12d3-a456-426614174000", {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ isActive: true })
});

// Deactivate a combo
await fetch("/api/combos/123e4567-e89b-12d3-a456-426614174000", {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ isActive: false })
});

```

### Method 2: CLI MCP Tool

Using the bundled CLI for scripted operations:

```bash

# Switch combo with ID `my-combo-id` on

omniroute mcp call omniroute_switch_combo '{"comboId":"my-combo-id","active":true}'

# Switch combo off

omniroute mcp call omniroute_switch_combo '{"comboId":"my-combo-id","active":false}'

```

### Method 3: Direct HTTP (curl)

For automation or external integrations:

```bash
curl -X PUT https://your.omniroute.instance/api/combos/my-combo-id \
  -H "Content-Type: application/json" \
  -d '{"isActive":false}'

```

## Key Source Files for Combo Switching

| Component | File Path | Purpose |
|-----------|-----------|---------|
| Tool schema definition | [`open-sse/mcp-server/schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/schemas/tools.ts) (lines 167–190) | Declares `omniroute_switch_combo` with input validation schema and `write:combos` scope requirement |
| Tool registration | [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) (lines 27–35) | Registers the tool and routes invocations to `handleSwitchCombo` |
| Switch handler implementation | [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) (lines 75–89) | Executes the `PUT` request, handles responses, and logs tool calls |
| Database persistence | [`src/lib/db/combos.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/combos.ts) (lines 99–106) | Provides `updateCombo` function for SQL operations |
| REST API endpoint | `src/app/api/combos/[id]/route.ts` (lines 101–119) | Validates and processes combo update requests |
| Resolver eligibility check | [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) | Filters combos by `isActive` flag during routing decisions |

## Common Use Cases for Combo Switching

- **A/B testing**: Activate experimental model chains alongside stable ones, using weighted routing to control traffic distribution
- **Maintenance windows**: Degrade gracefully by deactivating combos that depend on downstream services under maintenance
- **Cost optimization**: Switch off expensive model chains during low-traffic periods without losing configuration
- **Incident response**: Immediately isolate problematic combos when errors are detected, then reactivate after fixes

## Summary

- **Combo switching** toggles a model chain's eligibility in OmniRoute's routing engine via the `isActive` boolean flag
- The **`omniroute_switch_combo`** MCP tool (scope: `write:combos`) is the standard interface, translating calls to `PUT /api/combos/:id`
- The **`updateCombo`** function in [`src/lib/db/combos.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/combos.ts) persists changes to SQLite, with cache invalidation and audit logging
- The combo resolver in **[`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts)** enforces the active filter at request time
- Three interfaces are available: JavaScript fetch, CLI MCP tool, and direct HTTP

## Frequently Asked Questions

### What happens to in-flight requests when a combo is deactivated?

In-flight requests already routed to a combo complete normally; the `isActive` check only affects new resolution decisions. There is no forced termination of active connections.

### Can I schedule automatic combo activation and deactivation?

OmniRoute does not include built-in scheduling, but you can implement cron jobs or external orchestrators that call `omniroute_switch_combo` via the CLI or HTTP API at specified intervals.

### Is there a way to see which combos are currently active?

Query the `/api/combos` endpoint or use the corresponding MCP tool; the response includes the `isActive` field for each combo. The resolver also logs eligible combos at debug verbosity in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts).

### Does deactivating a combo affect its configuration data?

No. Deactivation only changes the `isActive` flag. All model definitions, routing strategy parameters, and metadata remain intact in the database and can be restored instantly by reactivating the combo.