mcp-compress-router 1.3.1 → 1.5.0

package/README.md

@@ -25,6 +25,7 @@
     - [Adding Downstream Servers](#adding-downstream-servers)
     - [Per-Server Enable/Disable](#per-server-enabledisable)
     - [Per-Server Tool Selection](#per-server-tool-selection)
+    - [Compression Levels](#compression-levels)
     - [Inspecting Tools](#inspecting-tools)
     - [OAuth](#oauth)
         - [Redirect URL](#redirect-url)
@@ -38,6 +39,7 @@
     - [Codex](#codex)
     - [GitHub Copilot](#github-copilot)
 - [How It Works](#how-it-works)
+- [Aknowledgements](#acknowledgements)
 
 ## The Problem
 
@@ -96,17 +98,17 @@ The router is published on npm as
 You do not need to install it — just run it with `npx`:
 
 ```bash
-npx mcp-compress-router add github -- npx -y @modelcontextprotocol/server-github
+npx mcp-compress-router@latest add playwright -- npx -y @playwright/mcp
 ```
 
-This registers a downstream MCP server named `github` and writes it to
-your [config file](#config-file-location). Repeat for every MCP server you
-want to compress.
+This registers a downstream MCP server named `playwright` and writes it
+to your [config file](#config-file-location). Repeat for every MCP server
+you want to compress.
 
 Then point your [coding agent](#connecting-coding-agents) at the router:
 
 ```bash
-npx mcp-compress-router
+npx mcp-compress-router@latest
 ```
 
 When started without a subcommand, the router runs the MCP server over
@@ -143,8 +145,9 @@ startup, so you can keep secrets out of the config (see
 
 > **Note on `-c` and credential storage:** when you override the config
 > path with `-c /some/dir/mcp.json`, both `credentials.json` (OAuth
-> tokens) and `mcp.json` live in `/some/dir/` — i.e. next to the config
-> file you specified. The `.env` file, however, is loaded from the
+> tokens) and `tools-cache.json` (cached tool schemas) will be stored
+> in that directory — i.e. next to the config file you specified. The
+> `.env` file, however, is loaded from the
 > [configuration directory](#config-file-location) resolved by
 > `MCP_COMPRESS_ROUTER_HOME` or the platform default, *not* from beside
 > the explicit `-c` path. To co-locate `.env` with a custom config, set
@@ -164,11 +167,11 @@ far better than a bare name.
 **stdio server** (a local process):
 
 ```bash
-npx mcp-compress-router add github --description "GitHub API tools" \
+npx mcp-compress-router@latest add github --description "GitHub API tools" \
   -- npx -y @modelcontextprotocol/server-github
 
 # With environment variables
-npx mcp-compress-router add github -e GITHUB_PERSONAL_TOKEN=ghp_xxx \
+npx mcp-compress-router@latest add github -e GITHUB_PERSONAL_TOKEN=ghp_xxx \
   --description "GitHub API tools" \
   -- npx -y @modelcontextprotocol/server-github
 ```
@@ -177,10 +180,10 @@ npx mcp-compress-router add github -e GITHUB_PERSONAL_TOKEN=ghp_xxx \
 URL):
 
 ```bash
-npx mcp-compress-router add my-http https://localhost:3100/mcp
+npx mcp-compress-router@latest add my-http https://localhost:3100/mcp
 
 # With a custom header
-npx mcp-compress-router add my-http \
+npx mcp-compress-router@latest add my-http \
   --header "Authorization: Bearer mytoken" \
   https://localhost:3100/mcp
 ```
@@ -213,9 +216,9 @@ supported. CLI commands write plain `.json`; hand-edited files may use
 Other management commands:
 
 ```bash
-npx mcp-compress-router list            # list all servers + auth status
-npx mcp-compress-router get my-http     # show one server's config
-npx mcp-compress-router remove my-http  # remove a server
+npx mcp-compress-router@latest list            # list all servers + auth status
+npx mcp-compress-router@latest get my-http     # show one server's config
+npx mcp-compress-router@latest remove my-http  # remove a server
 ```
 
 ### Per-Server Enable/Disable
@@ -230,14 +233,14 @@ enabled, keeping `mcp.json` clean and fully backward compatible.
 Toggle it from the CLI without touching the rest of the config:
 
 ```bash
-npx mcp-compress-router disable github   # writes "enabled": false
-npx mcp-compress-router enable github    # removes the field
+npx mcp-compress-router@latest disable github   # writes "enabled": false
+npx mcp-compress-router@latest enable github    # removes the field
 ```
 
 You can also set it at creation time:
 
 ```bash
-npx mcp-compress-router add archive --disabled -- npx -y server-archive
+npx mcp-compress-router@latest add archive --disabled -- npx -y server-archive
 ```
 
 ### Per-Server Tool Selection
@@ -274,12 +277,67 @@ hard error at startup. Set filters at creation time with repeatable
 flags:
 
 ```bash
-npx mcp-compress-router add github \
+npx mcp-compress-router@latest add github \
   --allowed-tools list_issues \
   --allowed-tools get_pull_request \
   -- npx -y server-github
 ```
 
+### Compression Levels
+
+Each server's tools are listed in the `get_tool_schema` description at a
+configurable `compressionLevel`. The level trades catalog compactness
+for routing detail: lower levels give the LLM more information up front
+(fewer `get_tool_schema` round-trips), while higher levels minimize the
+per-request token overhead. The full JSON parameter schema is always
+available via `get_tool_schema` regardless of the level — only the
+catalog *listing* changes.
+
+Four levels are supported, from most to least compact:
+
+| Level | Tool listing format | Description shown? |
+| --- | --- | --- |
+| `max` | `toolA, toolB, toolC` (comma-separated, single line) | No |
+| `high` (default) | `toolName(arg1, arg2)` (one per line) | No |
+| `medium` | `toolName(arg1, arg2): first sentence...` (one per line) | Snippet |
+| `low` | `<tool>toolName(arg1, arg2): full description</tool>` (one per line) | Full |
+
+Argument names are extracted from each tool's `inputSchema.properties`
+keys in definition order. When a tool has no description, the `medium`
+and `low` listings omit the description portion and show just the
+signature.
+
+Omitting `compressionLevel` (the default) is equivalent to `high`. Set
+it per server in `mcp.json`:
+
+```jsonc
+"github": {
+  "type": "stdio",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-github"],
+  "compressionLevel": "medium"
+}
+```
+
+Or set it at creation time with the `--compression-level` flag:
+
+```bash
+npx mcp-compress-router@latest add github \
+  --compression-level medium \
+  -- npx -y @modelcontextprotocol/server-github
+```
+
+A good rule of thumb:
+
+- Use `max` for servers whose tool names are self-describing and you
+  want the smallest possible catalog.
+- Use `high` (the default) for most servers — argument names are
+  usually enough for the LLM to pick the right tool.
+- Use `medium` when tool names alone are ambiguous and a one-line
+  hint helps disambiguate.
+- Use `low` sparingly — only when full descriptions must be visible
+  without a `get_tool_schema` call, since it costs the most tokens.
+
 ### Inspecting Tools
 
 To see exactly which tools a server advertises — and which are
@@ -287,7 +345,7 @@ To see exactly which tools a server advertises — and which are
 it live without starting the full router:
 
 ```bash
-npx mcp-compress-router tools github
+npx mcp-compress-router@latest tools github
 ```
 
 This works regardless of the server's `enabled` state (inspecting a
@@ -304,14 +362,16 @@ flow automatically if OAuth is advertised. You can also trigger it
 manually:
 
 ```bash
-npx mcp-compress-router login my-http
+npx mcp-compress-router@latest login my-http
 ```
 
 This opens your browser to complete the authorization-code flow. Tokens
 are stored in a separate `credentials.json` in the same directory as
 `mcp.json` (with `0600` permissions on Unix), so you can safely
-share or version-control `mcp.json` without exposing tokens. Add
-`credentials.json` to your `.gitignore`.
+share or version-control `mcp.json` without exposing tokens. Cached
+tool schemas are stored in `tools-cache.json` in the same directory.
+Add both `credentials.json` and `tools-cache.json` to your
+`.gitignore`.
 
 By default the router uses
 [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591).
@@ -354,7 +414,7 @@ ignore the port on `localhost`. If your provider demands a redirect URI
 with an **exact port**, pin it with `--port`:
 
 ```bash
-npx mcp-compress-router login my-http --port 8765
+npx mcp-compress-router@latest login my-http --port 8765
 ```
 
 This binds the callback server to `8765`, so the redirect URI becomes
@@ -374,7 +434,7 @@ flag each time:
 `--port` overrides `oauth.callbackPort` for a single run. Pass `--port 0`
 to force an OS-assigned port even when `oauth.callbackPort` is set.
 
-#### GitHub MCP (special case)
+#### GitHub MCP with OAuth (special case)
 
 The official GitHub MCP server at
 `https://api.githubcopilot.com/mcp` advertises OAuth but does **not**
@@ -392,7 +452,7 @@ organizations you want the MCP to access.
 3. **Add the GitHub MCP server by URL.**
 
    ```bash
-   npx mcp-compress-router add github https://api.githubcopilot.com/mcp
+   npx mcp-compress-router@latest add github https://api.githubcopilot.com/mcp
    ```
 
 4. **Set `oauth` credentials in `mcp.json`.**
@@ -419,7 +479,7 @@ organizations you want the MCP to access.
 5. **Run the login command.**
 
    ```bash
-   npx mcp-compress-router login github
+   npx mcp-compress-router@latest login github
    ```
 
    Your browser opens to authorize. After you approve, tokens are stored
@@ -430,7 +490,7 @@ organizations you want the MCP to access.
 > login will succeed, and its client secret is generated under *General*
 > → *Generate a new client secret*.
 
-#### Figma MCP (special case)
+#### Figma MCP with OAuth (special case)
 
 The official Figma MCP server at `https://mcp.figma.com/mcp` does **not**
 support Dynamic Client Registration through the standard MCP flow.
@@ -480,7 +540,7 @@ pin it with `oauth.callbackPort`.
 3. **Add the Figma MCP server by URL.**
 
    ```bash
-   npx mcp-compress-router add --transport http figma https://mcp.figma.com/mcp
+   npx mcp-compress-router@latest add --transport http figma https://mcp.figma.com/mcp
    ```
 
 4. **Set `oauth` credentials in `mcp.json`.**
@@ -507,7 +567,7 @@ pin it with `oauth.callbackPort`.
 5. **Run the login command.**
 
    ```bash
-   npx mcp-compress-router login figma
+   npx mcp-compress-router@latest login figma
    ```
 
    Your browser opens to authorize. After you approve, tokens are stored
@@ -516,7 +576,7 @@ pin it with `oauth.callbackPort`.
 Other OAuth commands:
 
 ```bash
-npx mcp-compress-router logout my-http  # remove stored credentials
+npx mcp-compress-router@latest logout my-http  # remove stored credentials
 ```
 
 For headless or CI environments, override the browser with the
@@ -525,7 +585,7 @@ URL is appended as a single final argument (no shell):
 
 ```bash
 MCP_COMPRESS_ROUTER_BROWSER="node /path/to/headless-browser.js" \
-  npx mcp-compress-router login my-http
+  npx mcp-compress-router@latest login my-http
 ```
 
 The default login timeout is 120 seconds; override it with
@@ -538,7 +598,7 @@ token instead of OAuth, use the `headers` field. You can set it via the
 CLI or directly in `mcp.json`:
 
 ```bash
-npx mcp-compress-router add my-http \
+npx mcp-compress-router@latest add my-http \
   --header "Authorization: Bearer mytoken" \
   --header "X-Custom: value" \
   https://example.com/mcp
@@ -584,68 +644,34 @@ Shell environment variables always take precedence over `.env` values.
 
 Once your downstream servers are configured, connect your agent to the
 router the same way you would connect any other MCP server — by
-pointing it at `npx mcp-compress-router`. The examples below assume the
+pointing it at `npx mcp-compress-router@latest`. The examples below assume the
 default [config location](#config-file-location); pass `-c <path>` if
 you use a custom one.
 
 ### Opencode
 
-Add the router to your `opencode.json` under `mcp`:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "mcp-compress-router": {
-      "type": "local",
-      "command": ["npx", "-y", "mcp-compress-router"],
-      "enabled": true
-    }
-  }
-}
+```sh
+opencode mcp add mcp-compress-router -- npx -y mcp-compress-router@latest
 ```
 
 ### Claude Code
 
-Add this to a project-level `.mcp.json` in your workspace root, or to
-your user-level config (applies to every project):
-
-- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-- **Linux:** `~/.config/Claude/claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "mcp-compress-router": {
-      "command": "npx",
-      "args": ["-y", "mcp-compress-router"]
-    }
-  }
-}
+```sh
+claude mcp add mcp-compress-router -- npx -y mcp-compress-router@latest
 ```
 
 ### Codex
 
-Add a `[mcp_servers.mcp-compress-router]` table to your Codex config (note
-the snake_case key). The config path is `~/.codex/config.toml` on
-macOS/Linux, or `%USERPROFILE%\.codex\config.toml` on Windows; you can
-also scope it to a single project via `.codex/config.toml` in trusted
-projects.
-
-```toml
-[mcp_servers.mcp-compress-router]
-command = "npx"
-args = ["-y", "mcp-compress-router"]
-enabled = true
+```sh
+codex mcp add mcp-compress-router -- npx -y mcp-compress-router@latest
 ```
 
-### GitHub Copilot
+### GitHub Copilot (VS Code)
 
 Add this to `.vscode/mcp.json` in your workspace (project-level, applies
 only to that workspace), or to your **user-level** MCP settings which
-apply across every workspace: open the Command Palette →
-`Preferences: Open User Settings (JSON)` and add the same `servers`
+apply across every workspace: open the Command Palette (`Cmd+Shift+P`) →
+`MCP: Open User Configuration` and add the same `servers`
 block under the `mcp` key. Project-level and user-level entries are
 merged, with project-level taking precedence.
 
@@ -654,7 +680,7 @@ merged, with project-level taking precedence.
   "servers": {
     "mcp-compress-router": {
       "command": "npx",
-      "args": ["-y", "mcp-compress-router"]
+      "args": ["-y", "mcp-compress-router@latest"]
     }
   }
 }
@@ -684,3 +710,11 @@ token catalog, regardless of how many downstream servers you have.
 
 For the full configuration and environment variable reference, see
 [configuration.md](docs/configuration.md).
+
+## Acknowledgements
+
+- [mcp2cli](https://github.com/knowsuchagency/mcp2cli) — a very similar
+  idea of how MCP can be compressed, but to a CLI.
+- [mcp-compressor](https://github.com/atlassian-labs/mcp-compressor) —
+  also a very similar idea; the "two tools" approach was borrowed from
+  this project, though it only compresses a single MCP server.

package/build/cli/add-command.js

@@ -1,5 +1,5 @@
 import { ensureConfigDir, readConfigFile, writeConfigFile, readCredentials, writeCredentials, } from './config-io.js';
-import { validateGlobPattern } from '../utils/index.js';
+import { isCompressionLevel, validateGlobPattern, VALID_COMPRESSION_LEVELS, } from '../utils/index.js';
 /**
  * Validates every glob pattern in an optional tool list, throwing with
  * the field name and offending pattern on the first invalid entry.
@@ -61,6 +61,9 @@ function buildServerEntry(opts) {
     if (opts.disabledTools && opts.disabledTools.length > 0) {
         entry.disabledTools = opts.disabledTools;
     }
+    if (opts.compressionLevel) {
+        entry.compressionLevel = opts.compressionLevel;
+    }
     // A fixed callback port only applies to HTTP servers (OAuth). Persist
     // it on the `oauth` block so `login` reuses the same redirect URI.
     if (opts.port !== undefined) {
@@ -92,6 +95,10 @@ export async function handleAdd(configPath, opts) {
     }
     validateToolListPatterns('allowedTools', opts.allowedTools);
     validateToolListPatterns('disabledTools', opts.disabledTools);
+    if (opts.compressionLevel !== undefined && !isCompressionLevel(opts.compressionLevel)) {
+        throw new Error(`Invalid "--compression-level" value "${opts.compressionLevel}": ` +
+            `must be one of ${VALID_COMPRESSION_LEVELS.join(', ')}.`);
+    }
     await ensureConfigDir(configPath);
     const servers = await readConfigFile(configPath);
     if (opts.name in servers) {

package/build/cli/get-command.js

@@ -24,6 +24,12 @@ export async function handleGet(configPath, name) {
     if (entry.description) {
         lines.push(`Description: ${entry.description}`);
     }
+    if (entry.compressionLevel) {
+        lines.push(`compressionLevel: ${entry.compressionLevel}`);
+    }
+    else {
+        lines.push('compressionLevel: high (default)');
+    }
     if (entry.command) {
         lines.push(`Command: ${entry.command}`);
     }

package/build/cli/list-command.js

@@ -55,6 +55,16 @@ function summarizeTools(server) {
     }
     return 'all';
 }
+/**
+ * Renders the `Compression` cell: the explicit `compressionLevel`, or
+ * `high` when the field is absent (the default per PRD §"Solution").
+ *
+ * @param server - Typed downstream server config.
+ * @returns The resolved compression level string.
+ */
+function summarizeCompression(server) {
+    return server.compressionLevel ?? 'high';
+}
 /**
  * Renders the list header and server rows as a fixed-width table. The
  * final (Auth) column is left unpadded so lines never carry trailing
@@ -74,13 +84,14 @@ function formatList(configPath, rows) {
     const commandWidth = Math.max('CommandOrUrl'.length, ...rows.map((r) => r.commandOrUrl.length));
     const enabledWidth = Math.max('Enabled'.length, ...rows.map((r) => r.enabled.length));
     const toolsWidth = Math.max('Tools'.length, ...rows.map((r) => r.tools.length));
+    const compressionWidth = Math.max('Compression'.length, ...rows.map((r) => r.compression.length));
     const pad = (val, width) => val.padEnd(width);
-    const columns = (name, type, command, enabled, tools, auth) => `${pad(name, nameWidth)}  ${pad(type, typeWidth)}  ${pad(command, commandWidth)}  ${pad(enabled, enabledWidth)}  ${pad(tools, toolsWidth)}  ${auth}`;
+    const columns = (name, type, command, enabled, tools, compression, auth) => `${pad(name, nameWidth)}  ${pad(type, typeWidth)}  ${pad(command, commandWidth)}  ${pad(enabled, enabledWidth)}  ${pad(tools, toolsWidth)}  ${pad(compression, compressionWidth)}  ${auth}`;
     return [
         header,
         '',
-        columns('Name', 'Type', 'CommandOrUrl', 'Enabled', 'Tools', 'Auth'),
-        ...rows.map((r) => columns(r.name, r.type, r.commandOrUrl, r.enabled, r.tools, r.auth)),
+        columns('Name', 'Type', 'CommandOrUrl', 'Enabled', 'Tools', 'Compression', 'Auth'),
+        ...rows.map((r) => columns(r.name, r.type, r.commandOrUrl, r.enabled, r.tools, r.compression, r.auth)),
     ].join('\n');
 }
 /**
@@ -107,6 +118,7 @@ export async function handleList(configPath) {
             enabled: entry.enabled,
             allowedTools: entry.allowedTools,
             disabledTools: entry.disabledTools,
+            compressionLevel: entry.compressionLevel,
         };
         return {
             name,
@@ -114,6 +126,7 @@ export async function handleList(configPath) {
             commandOrUrl: buildCommandOrUrl(typed),
             enabled: summarizeEnabled(typed),
             tools: summarizeTools(typed),
+            compression: summarizeCompression(typed),
             auth: computeAuthStatus(typed, credentials[name]),
         };
     });

package/build/cli/login-command.js

@@ -1,6 +1,7 @@
+import { Logger } from '../utils/index.js';
 import { ensureConfigDir, readConfigFile } from './config-io.js';
 import { loadConfig } from '../services/config.js';
-import { discoverAuth } from '../services/index.js';
+import { discoverAuth, discoverSingleServer, saveToolCache } from '../services/index.js';
 /**
  * Validates that a server exists in config and is eligible for OAuth login.
  *
@@ -260,5 +261,16 @@ export async function handleLogin(configPath, name, portOverride) {
         redirectUri: realRedirectUrl,
     });
     await mgr.saveTokens(tokens);
+    // Best-effort: discover tools and save to cache so the next router
+    // startup (or self-recovery) has an up-to-date cache.
+    try {
+        const logger = new Logger('error');
+        const discovered = await discoverSingleServer(targetServer, logger, () => mgr);
+        await saveToolCache(configPath, name, discovered.tools);
+    }
+    catch {
+        // Best-effort — tokens are saved, cache will refresh on next
+        // router startup.
+    }
     return `Successfully authenticated server "${name}". Tokens stored in credentials.json.`;
 }

package/build/cli/register-commands.js

@@ -84,6 +84,7 @@ function buildAddOptions(name, commandOrUrl, rest, options) {
         allowedTools: options.allowedTools && options.allowedTools.length > 0 ? options.allowedTools : undefined,
         disabledTools: options.disabledTools && options.disabledTools.length > 0 ? options.disabledTools : undefined,
         port: options.port,
+        compressionLevel: options.compressionLevel || undefined,
     };
 }
 function registerAddCommand(program) {
@@ -99,6 +100,7 @@ function registerAddCommand(program) {
         .option('--disabled', 'mark the server as disabled (writes "enabled": false)')
         .option('--allowed-tools <pattern>', 'glob pattern allowlisting tool names (repeatable)', collectStringArray, [])
         .option('--disabled-tools <pattern>', 'glob pattern denylisting tool names (repeatable)', collectStringArray, [])
+        .option('--compression-level <level>', 'tool listing compression level (max, high, medium, low; default high)')
         .option('-p, --port <number>', 'fixed local OAuth callback port (HTTP only; written to oauth.callbackPort)', parsePort)
         .action(guardedAction(async (name, commandOrUrl, rest, options) => {
         const configPath = await resolveConfigPath(options.config);

package/build/cli/router-runner.js

@@ -1,31 +1,50 @@
-import { resolveConfigPath, invokeDownstreamTool, OAuthCredentialManager, persistAuthRequirements, loadConfig, connectAndDiscover, buildCatalog, } from '../services/index.js';
+import { resolveConfigPath, persistAuthRequirements, loadConfig, ServerConnection, invokeWithRecovery, buildCatalog, } from '../services/index.js';
 import { Logger } from '../utils/index.js';
 import { createGetToolSchemaHandler, buildGetToolSchemaDescription, GetToolSchemaInputSchema, createInvokeToolHandler, InvokeToolInputSchema, } from '../tools/index.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 /**
- * Creates OAuth credential managers for HTTP servers that have stored
- * credentials or oauth overrides, so the transport can handle auth.
+ * Connects to all enabled downstream servers via ServerConnection.
+ * Disabled servers are skipped entirely. On failure, warm-cache
+ * servers are degraded; cold-cache servers cause fail-fast.
+ *
+ * @param servers - Validated downstream server configs.
+ * @param configPath - Absolute path to the config file.
+ * @param logger - Structured logger.
+ * @returns Map of server name to ServerConnection and discovered data.
+ * @throws When a server cannot connect AND has no tool cache.
  */
-async function buildAuthProviders(resolved, servers) {
-    const authProviders = new Map();
-    for (const server of servers) {
-        if (server.type === 'http' || server.type === 'streamable-http') {
-            const mgr = new OAuthCredentialManager(resolved, server);
-            const hasCredentials = (await mgr.tokens()) !== undefined;
-            const hasOverrides = server.oauth?.clientId !== undefined;
-            if (hasCredentials || hasOverrides) {
-                authProviders.set(server.name, mgr);
-            }
+async function connectAllServers(servers, configPath, logger) {
+    const enabledServers = servers.filter((server) => {
+        if (server.enabled === false) {
+            logger.info(`Skipping disabled server "${server.name}"`, { server: server.name });
+            return false;
         }
+        return true;
+    });
+    const results = await Promise.all(enabledServers.map(async (server) => {
+        const conn = new ServerConnection(server, configPath, logger);
+        const ds = await conn.connect();
+        return { conn, ds };
+    }));
+    const connections = new Map();
+    const discovered = [];
+    for (const { conn, ds } of results) {
+        connections.set(conn.serverName, conn);
+        discovered.push(ds);
     }
-    return authProviders;
+    return { connections, discovered };
 }
 /**
  * Creates the MCP server, registers router tools, and starts the
  * stdio transport.
+ *
+ * @param catalog - The mutable tool catalog.
+ * @param connections - Live ServerConnection instances keyed by name.
+ * @param selectionByServer - Per-server tool selection for re-filtering.
+ * @param logger - Structured logger.
  */
-async function startRouterServer(catalog, clients, logger) {
+async function startRouterServer(catalog, connections, selectionByServer, logger) {
     const router = new McpServer({
         name: 'mcp-compress-router',
         version: '1.0.0',
@@ -35,7 +54,9 @@ async function startRouterServer(catalog, clients, logger) {
         description: buildGetToolSchemaDescription(catalog),
         inputSchema: GetToolSchemaInputSchema,
     }, createGetToolSchemaHandler(catalog, logger));
-    const invokeFn = (server, tool, args) => invokeDownstreamTool(clients, server, tool, args, logger);
+    const invokeFn = async (server, tool, args) => {
+        return invokeWithRecovery(server, tool, args, catalog, connections, selectionByServer, logger);
+    };
     router.registerTool('invoke_tool', {
         title: 'Invoke Tool',
         description: 'Invoke a specific tool on a connected MCP server. ' +
@@ -66,26 +87,26 @@ export async function runRouter(configPath, verbose) {
     const servers = await loadConfig(resolved);
     logger.info('Configuration loaded', { serverCount: servers.length });
     await persistAuthRequirements(resolved, servers, logger);
-    const authProviders = await buildAuthProviders(resolved, servers);
-    const getAuthProvider = (server) => authProviders.get(server.name);
     logger.info('Connecting to downstream servers', {
         servers: servers.map((s) => s.name),
     });
-    const { servers: discovered, clients } = await connectAndDiscover(servers, logger, getAuthProvider);
+    const { connections, discovered } = await connectAllServers(servers, resolved, logger);
     logger.info('Tools discovered', {
         servers: discovered.map((d) => ({
             name: d.name,
             toolCount: d.tools.length,
-            tools: d.tools.map((t) => t.name),
+            status: d.status,
         })),
     });
     const selectionByServer = new Map();
+    const compressionLevelByServer = new Map();
     for (const server of servers) {
         selectionByServer.set(server.name, {
             allowedTools: server.allowedTools,
             disabledTools: server.disabledTools,
         });
+        compressionLevelByServer.set(server.name, server.compressionLevel);
     }
-    const catalog = buildCatalog(discovered, selectionByServer, logger);
-    await startRouterServer(catalog, clients, logger);
+    const catalog = buildCatalog(discovered, selectionByServer, logger, compressionLevelByServer);
+    await startRouterServer(catalog, connections, selectionByServer, logger);
 }

package/build/services/auth-errors.js

@@ -0,0 +1,22 @@
+/**
+ * Tagged error thrown when a downstream server requires OAuth
+ * authentication that cannot be completed from the running router
+ * process.
+ *
+ * The MCP SDK calls `OAuthClientProvider.redirectToAuthorization()` on
+ * a 401 response. This error is thrown from that method so callers
+ * can discriminate auth failures from other errors (network, config,
+ * transport) without relying on substring matching of error messages.
+ */
+export class GuidedAuthError extends Error {
+    /** The downstream server name that requires authentication. */
+    serverName;
+    /**
+     * @param serverName - The name of the server requiring authentication.
+     */
+    constructor(serverName) {
+        super(`Authentication required for server "${serverName}".`);
+        this.name = 'GuidedAuthError';
+        this.serverName = serverName;
+    }
+}