mcp-facade

Una fachada MCP genérica: un proceso stdio se sitúa delante de un servidor MCP upstream y expone solo un subconjunto configurado de sus herramientas, con esquemas compactados, más tres meta-herramientas (discover, describe, call) que mantienen el resto del catálogo accesible bajo demanda.

Por qué

Cada herramienta que expone un servidor MCP se inyecta en el contexto del modelo como un esquema JSON en cada solicitud. Un servidor grande con 40 herramientas puede costar decenas de miles de tokens por sesión antes de que se realice ningún trabajo: la mayor parte de ese coste se debe a herramientas que nunca se llaman.

La fachada le da la vuelta a la ecuación de costes: solo pagas tokens de esquema completos por las herramientas que realmente usas (las incluidas en used), compactadas a lo esencial. Todo lo demás sigue siendo descubrible a través de las meta-herramientas, que en total cuestan tres esquemas pequeños.

Related MCP server: @zhangzwd/mcp-gateway

Qué hace

• Se ejecuta como un servidor MCP stdio: bun run facade.ts --server <name>. Un proceso por servidor upstream.

• Lee facade.servers.json (junto a facade.ts) y elige la entrada <name>.

• Ante la primera tools/list, obtiene el catálogo upstream y lo guarda en una memoria caché en disco (~/.omp/agent/mcp-facade/catalogs/<name>.json, TTL de 7 días). La conexión con el upstream es perezosa: no se establece ninguna conexión hasta el primer uso.

• Sirve cada herramienta de used con un esquema compactado:

  • cada cadena description (a nivel de herramienta y dentro del esquema JSON) se reduce a su primera frase, con un máximo de 140 caracteres;

  • las claves $comment, examples y default se eliminan recursivamente;

  • la estructura (types, properties, required, enums) se mantiene intacta;

  • los nombres de las herramientas se pasan a minúsculas; la búsqueda no distingue mayúsculas.

• Siempre añade las tres meta-herramientas (ver más abajo).

• Si el catálogo no se puede obtener en el momento de tools/list, se degrada a servir únicamente las meta-herramientas y registra el motivo en stderr.

• Reenvía las llamadas al upstream. Para upstreams HTTP con un credentialId, un error 401/no autorizado/token caducado desencadena un refresco forzado del token y un único reintento.

Las meta-herramientas

Flujo típico de un agente: discover "worklog" → describe addworklog → call { tool: "addworklog", args: { ... } }.

Requisitos

• Bun (la fachada ejecuta TypeScript directamente).

• Para upstreams HTTP protegidos con OAuth: tener la CLI de OMP omp instalada en ~/.bun/bin/omp, con la credencial ya autorizada. La fachada obtiene los tokens mediante omp token <credentialId> (y omp token --force-refresh <credentialId> al reintentar). Los secretos nunca se almacenan en la configuración.

• Para los upstreams stdio que necesiten variables de entorno (claves de API, tokens): una configuración de host de Claude existente en ~/.claude.json que contenga el bloque env de ese servidor (ver envFrom más adelante).

Instalación

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

facade.servers.json está en el fichero .gitignore — puede contener rutas locales.

Configuración

facade.servers.json asocia un nombre de servidor con su upstream y la lista de herramientas usadas:

{
  "<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

      // …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
  }
}

Notas:

• Las entradas de used se buscan sin distinguir mayúsculas y se sirven en minúsculas.

• envFrom por ahora solo admite el prefijo claude:<name>.

• Una lista used vacía es válida: en ese caso la fachada expone solo las meta-herramientas.

Registro en un host

Apunta la configuración MCP de tu host a la fachada, un entrada por cada upstream:

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

⚠️ stdout es el protocolo

El transporte stdio es propietario de stdout. Nunca se escriban registros, diagnósticos o salidas de depuración en stdout: cualquier dato en stdout corromve el flujo JSON-RPC y bloquea el host. La fachada solo registra en stderr (console.error); mantén este comportamiento también en cualquier variante.

Limitaciones

• Rutas fijas: caché del catálogo en ~/.omp/agent/mcp-facade/catalogs/, binario de OMP en ~/.bun/bin/omp, y envFrom solo lee ~/.claude.json.

• El catálogo se obtiene con una sola llamada listTools: no hay paginación ni gestión de tools/list_changed. Reinicia la fachada (o espera a que pase el TTL de 7 días) para incorporar los cambios de herramientas del upstream.

• El discover es una simple coincidencia de substring, limitada a 10 resultados.

• Se permite un reintento ante un error de autenticación; el resto de errores del upstream se propagan tal cual.

• No hay soporte para prompts, recursos ni sampling del upstream: solo herramientas.