mcp-facade
mcp-facade
一个通用的 MCP 门面(facade):一个 stdio 进程位于上游 MCP 服务器之前,只暴露其工具的一个已配置子集——使用压缩后的 schema——外加三个元工具(discover、describe、call),让目录的其余部分按需可访问。
为什么
每个 MCP 服务器暴露的工具都会以 JSON schema 的形式注入模型上下文,并且在每次请求上都是如此。一个拥有 40 个工具的臃肿服务器,在开始任何工作之前就可能让会话花费数万 token——其中大部分是你从未调用过的工具。
门面扭转了这种成本结构:你只为实际使用的工具(在 used 中列出)支付完整的 schema token,而且这些 schema 被压缩到最核心的部分。其余所有工具仍然可以通过元工具发现,元工具总共只需要三个很小的 schema。
Related MCP server: @zhangzwd/mcp-gateway
功能
作为 stdio MCP 服务器运行:
bun run facade.ts --server <name>。每个上游服务器对应一个进程。读取
facade.servers.json(位于facade.ts旁)并选取<name>条目。在第一次
tools/list时获取上游目录并缓存到磁盘(~/.omp/agent/mcp-facade/catalogs/<name>.json,7 天 TTL)。上游连接是惰性的——首次使用前不会建立连接。以下列方式提供
used中每个工具的压缩 schema:每个
description字符串(工具级以及 JSON schema 内部)被截断到第一句,最多 140 个字符;$comment、examples和default键会被递归删除;结构(类型、属性、required、enums)保持不变;
工具名转换为小写;查找时不区分大小写。
总是附加这三个元工具(见下文)。
如果在
tools/list时无法获取目录,则降级为仅提供元工具,并将原因记录到 stderr。将调用转发给上游。对于带有
credentialId的 HTTP 上游,401/未授权/令牌过期错误会触发一次令牌强制刷新和一次重试。
元工具
工具 | 用途 |
| 按关键字搜索完整的上游目录(名称 + 描述,子串匹配,最多 10 条结果)。返回 |
| 按小写名称返回某个工具的完整原始 schema 和文档。在调用不熟悉的工具之前先使用。 |
| 按名称调用任意上游工具,并传入 |
典型的智能体流程:discover "worklog" → describe addworklog → call { tool: "addworklog", args: { ... } }。
要求
Bun(门面直接运行 TypeScript)。
对于受 OAuth 保护的 HTTP 上游:已在
~/.bun/bin/omp安装 OMPompCLI,且凭证已完成授权。门面通过omp token <credentialId>获取令牌(并在重试时使用omp token --force-refresh <credentialId>)。机密信息从不存储在配置中。对于需要环境变量(API 密钥、令牌)的 stdio 上游:在
~/.claude.json中需有一个现有的 Claude 主机配置,其中包含该服务器的env块(见下面的envFrom)。
安装
bun install
cp facade.servers.example.json facade.servers.json # then editfacade.servers.json 被 gitignore 忽略——它可能包含本地路径。
配置
facade.servers.json 将服务器名称映射到其上游和已用工具列表:
{
"<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
}
}注意:
used条目不区分大小写匹配,并且以小写形式提供服务。envFrom目前仅支持claude:<name>前缀。空的
used列表有效:此时门面只暴露元工具。
注册到主机
将主机和 MCP 配置指向门面,每个上游一个条目:
{
"mcpServers": {
"acme": {
"command": "/path/to/bun",
"args": ["run", "/path/to/mcp-facade/facade.ts", "--server", "acme-http"]
}
}
}⚠️ stdout 是协议
stdio 传输占用 stdout。绝不将日志、诊断或调试输出写入 stdout——stdout 上的任何输出都会破坏 JSON-RPC 流并卡死主机。门面只向 stderr(console.error)记录日志;任何分支中都要保持这一点。
局限性
硬编码路径:目录缓存位于
~/.omp/agent/mcp-facade/catalogs/,OMP 二进制文件位于~/.bun/bin/omp,envFrom只读取~/.claude.json。目录用一次
listTools F调用获取——没有分页,也不处理tools/list_changed。重启门面(或等待 7 天 TTL 过期)以获取上游工具变更。discover是简单的子串匹配,最多返回 10 个结果。认证失败时只重试一次;其他上游错误原样传播。
不支持上游的 prompts、resources 或 sampling——仅支持工具。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Toolstile is a managed MCP gateway that connects remote MCP servers behind one endpoint, with per-agent permissions, shared accounts and activity logs. Connect at https://mcp.toolstile.com/mcp over Streamable HTTP with OAuth; sign in at https://toolstile.com, select a workspace and connect your upstream servers. Available tools, resources and prompts depend on that workspace and the agent's granted access.
Stdio MCP proxy: free probe, then x402-paid ReadFetch tools; for hosts that cannot sign x402.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Stateless MCP gateway and OTel span-streaming bridge for hosted MCP servers.
Related MCP Servers
- AlicenseAqualityBmaintenanceA stdio MCP proxy that connects to one or more upstream MCP servers and exposes their tools, resources, and prompts through a single endpoint with a configurable middleware pipeline.14186 npm3MIT
- AlicenseNot gradedqualityDmaintenanceA lightweight MCP gateway that aggregates multiple MCP services into a unified stdio interface, automatically prefixing tool names with the service name to avoid conflicts.13 npmMIT
- AlicenseNot gradedqualityCmaintenanceServes any OpenAPI 3.x/Swagger 2.x API as a local MCP server over stdio, converting every operation into a tool that proxies requests to the upstream API with configurable headers and fixed parameters.6 npm1MIT
- AlicenseNot gradedqualityCmaintenanceA deterministic MCP tool-list relay that lets operators filter tools by include/exclude rules and exposes a filtered stdio MCP server to local clients.10 npmMIT