mcp-facade

A generic MCP facade: one stdio process sits in front of an upstream MCP server and exposes only a configured subset of its tools — with compacted schemas — plus three meta-tools (discover, describe, call) that keep the rest of the catalog reachable on demand.

Why

Every tool an MCP server exposes is injected into the model's context as a JSON schema on every request. A fat server with 40 tools can cost tens of thousands of tokens per session before any work happens — most of it for tools you never call.

The facade flips the economics: you pay full schema tokens only for the tools you actually use (listed in used), compacted to their essentials. Everything else stays discoverable through the meta-tools, which cost three small schemas total.

Related MCP server: @zhangzwd/mcp-gateway

What it does

• Runs as a stdio MCP server: bun run facade.ts --server <name>. One process per upstream server.

• Reads facade.servers.json (next to facade.ts) and picks the <name> entry.

• On the first tools/list, fetches the upstream catalog and caches it to disk (~/.omp/agent/mcp-facade/catalogs/<name>.json, 7-day TTL). The upstream connection is lazy — nothing connects until first use.

• Serves each used tool with a pruned schema:

  • every description string (tool-level and inside the JSON schema) is cut to its first sentence (tool-level max 140 chars, field-level max 100);

  • $comment, examples, default, and additionalProperties keys are dropped recursively;

  • recursion follows required fields; optional subtrees collapse to { "type": …, "description": "≤60 chars" }, so a fat optional branch costs one line instead of dozens;

  • the full original shape stays one describe hop away;

  • tool names are lowercased; lookup is case-insensitive.

• Always appends the three meta-tools (see below).

• If the catalog can't be fetched at tools/list time, it degrades to serving the meta-tools only and logs the reason to stderr.

• Forwards calls to the upstream. For HTTP upstreams with a credentialId, a 401/unauthorized/expired-token error triggers one token force-refresh and a single retry.

The meta-tools

Typical agent flow: discover "worklog" → describe addworklog → call { tool: "addworklog", args: { ... } }.

Requirements

• Bun (the facade runs TypeScript directly).

• For OAuth-protected HTTP upstreams: the OMP omp CLI installed at ~/.bun/bin/omp, with the credential already authorized. The facade fetches tokens via omp token <credentialId> (and omp token --force-refresh <credentialId> on retry). Secrets are never stored in the config.

• For stdio upstreams that need env vars (API keys, tokens): an existing Claude host config at ~/.claude.json holding that server's env block (see envFrom below).

Install

bun install
cp facade.servers.example.json facade.servers.json   # then edit

facade.servers.json is gitignored — it may contain local paths.

Configuration

facade.servers.json maps a server name to its upstream and used-tools list:

{
  "<name>": {
    "upstream": {
      // HTTP upstream (Streamable HTTP transport):
      "url": "https://mcp.example.com/v1/mcp",
      "credentialId": "mcp_oauth:profile:default:https://mcp.example.com/v1/mcp" // optional
      // optional: direct OAuth refresh on 401 (see refresh.ts). Never put the
      // secret itself in config — reference it:
      "oauth": {
      //   "tokenUrl": "https://example.com/v1/token",
      //   "clientId": "<client-id>",
      //   "clientSecretFrom": "keychain:<service>" | "env:<VAR>", // omit for public clients
      //   "authStyle": "body" | "basic" // body = default; basic required by Figma
      }
      // …or stdio upstream:
      // "command": "/usr/local/bin/npx",
      // "args": ["-y", "@example/mcp-server"],
      // "envFrom": "claude:<server-name>",  // optional: pull env from ~/.claude.json mcpServers.<server-name>.env
      // "env": { "EXTRA": "value" }          // optional: merged on top
    },
    "used": ["tool_one", "tool_two"]  // exposed directly; everything else via meta-tools
  }
}

Notes:

• used entries are matched case-insensitively and served lowercased.

• envFrom currently only supports the claude:<name> prefix.

• An empty used list is valid: the facade then exposes only the meta-tools.

Registering with a host

Point your host's MCP config at the facade, one entry per upstream:

{
  "mcpServers": {
    "acme": {
      "command": "/path/to/bun",
      "args": ["run", "/path/to/mcp-facade/facade.ts", "--server", "acme-http"]
    }
  }
}

⚠️ stdout is protocol

The stdio transport owns stdout. Never write logs, diagnostics, or debug output to stdout — anything on stdout corrupts the JSON-RPC stream and wedges the host. The facade logs only to stderr (console.error); keep it that way in any fork.

Limitations

• Hardcoded paths: catalog cache at ~/.omp/agent/mcp-facade/catalogs/, OMP binary at ~/.bun/bin/omp, envFrom reads ~/.claude.json only.

• Catalog is fetched with a single listTools call — no pagination, no tools/list_changed handling. Restart the facade (or wait out the 7-day TTL) to pick up upstream tool changes.

• discover is a simple substring match, capped at 10 results.

• One retry on auth failure; other upstream errors propagate as-is.

• No support for upstream prompts, resources, or sampling — tools only.