Routing Engine

The routing engine is MCPlexer's decision layer. When a tool call arrives, the engine evaluates route rules to determine whether the call is allowed, denied, or requires approval — and which downstream server handles it.

Route Rule Fields

Evaluation Model

Deny-First

At each priority level, deny rules are evaluated before allow rules. If a deny rule matches, the tool call is immediately blocked — no further rules are checked.

This ensures that security restrictions always take precedence over permissive rules at the same priority.

Priority System

Rules are evaluated in ascending priority order (lower number = higher priority). Within the same priority, deny rules come first.

Short-Circuit Behavior

Once a matching rule is found, evaluation stops. The first match wins. If no rule matches in any workspace (after fallback), the workspace's default_policy applies.

Path Glob Matching

The path_glob field uses Go's filepath.Match patterns against the subpath — the client's CWD relative to the workspace root.

Example

Tool Pattern Matching

The tool_match field takes an array of glob patterns matched against the full namespaced tool name (e.g., github__create_issue).

Multiple patterns in the array are OR-matched — a tool call matches if it matches any pattern.

Namespace-Aware Matching

Route rules are inherently namespace-aware because tool names always include the namespace prefix. A rule targeting github__* will only match tools from the GitHub downstream server.

Workspace Ancestor Fallback

When no rule matches in the directly-matched workspace, MCPlexer walks up the directory tree and evaluates rules in each ancestor workspace:

1. Check rules in the matched workspace (most specific)
2. Check rules in the parent workspace (if one exists)
3. Continue up through ancestor workspaces
4. Check the global workspace (root="")
5. If still no match, apply the matched workspace's default_policy

This allows you to define broad rules at higher-level workspaces and override them at more specific levels.

Common Patterns

Allow Specific Tools, Deny Everything Else

Set default_policy: deny on the workspace, then add allow rules for specific tools:

workspaces:
  - name: "Production"
    root_path: "/srv/app"
    default_policy: deny

route_rules:
  - name: "Allow read-only GitHub"
    workspace_id: production
    tool_match: ["github__list_*", "github__get_*"]
    downstream_server_id: github
    policy: allow
    priority: 50

Block Destructive Tools

Use a high-priority deny rule to prevent destructive operations:

route_rules:
  - name: "Deny destructive filesystem ops"
    workspace_id: production
    tool_match: ["fs__write_*", "fs__delete_*", "fs__move_*"]
    downstream_server_id: filesystem
    policy: deny
    priority: 10

Require Approval for Writes

Allow write tools, but hold them for human review:

route_rules:
  - name: "Approve GitHub writes"
    workspace_id: default
    tool_match: ["github__create_*", "github__update_*", "github__delete_*"]
    downstream_server_id: github
    policy: allow
    requires_approval: true
    approval_timeout: 120
    priority: 50

Path-Scoped Rules

Restrict tools to specific subdirectories:

route_rules:
  - name: "Allow DB tools in migrations only"
    workspace_id: acme
    path_glob: "migrations/**"
    tool_match: ["db__*"]
    downstream_server_id: database
    policy: allow
    priority: 50

  - name: "Deny DB tools everywhere else"
    workspace_id: acme
    tool_match: ["db__*"]
    downstream_server_id: database
    policy: deny
    priority: 60

Route Caching

The routing engine caches rules per workspace with a 30-second TTL. After a rule is created, updated, or deleted via the API, the cache expires within 30 seconds.