mcp-facade

범용 MCP 파사드(facade): 하나의 stdio 프로세스가 업스트림 MCP 서버 앞에 자리하며, 구성된 도구들의 하위 집합만 노출합니다 — 압축된 스키마를 포함해서 — 그리고 나머지 카탈로그를 요청 시 접근 가능하게 유지하는 세 가지 메타 도구(discover, describe, call)를 제공합니다.

왜

MCP 서버가 노출하는 모든 도구는 모든 요청에서 JSON 스키마로 모델의 컨텍스트에 주입됩니다. 도구 40개를 가진 비대한 서버는 실제 작업이 시작되기 전에 세션당 수만 개의 토큰을 소모할 수 있습니다 — 대부분 전혀 호출하지 않는 도구 때문입니다.

파사드는 이런 비용 구조를 뒤집습니다: 실제 사용하는 도구(used에 나열된)에 대해서만 전체 스키마 토큰을 지불하고, 그것들도 필수 요소만 남겨 압축됩니다. 나머지 모든 것은 메타 도구를 통해 계속 발견 가능하며, 메타 도구는 총 세 개의 작은 스키마만 차지합니다.

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). 업스테림 연결은 지연(lazy) 방식입니다 — 처음 사용하기 전에는 아무것도 연결되지 않습니다.

• 각 used 도구를 압축된 스키마로 제공합니다:

  • 모든 description 문자열(도구 수준과 JSON 스키마 내부)은 첫 문장까지만 잘리되, 최대 140자;

  • $comment, examples, default 키는 재귀적으로 제거됩니다;

  • 구조(types, properties, required, enums)는 그대로 유지됩니다;

  • 도구 이름은 소문자로 변환됩니다. 조회 시 대소문자를 구분하지 않습니다.

• 항상 세 가지 메타 도구를 추가합니다(아래 참조).

• tools/list 시점에 카탈로그를 가져오지 못하면 메타 도구만 제공하는 것으로 저하(degrade)되며, 그 이유를 stderr에 기록합니다.

• 호출을 업스트림으로 전달합니다. credentialId가 있는 HTTP 업스트림의 경우 401/unauthorized/expired-token 오류가 발생하면 토큰 강제 갱신을 한 번 트리거하고 재시도도 한 번 합니다.

메타 도구

전형적인 에이전트 흐름: discover "worklog" → describing addworklog → call { tool: "addworklog", args: { ... } }.

요구 사항

• Bun (파사드는 TypeScript를 직접 실행합니다).

• OAuth 보호 HTTP 업스트림: ~/.bun/bin/omp에 설치된 OMP omp CLI가 필요하며, 해당 자격 증명이 이미 인증되어 있어야 합니다. 파사드는 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 edit

facade.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 호출로 가져옵니다 — 페이징 처리도 tools/list_changed 처리도 없습니다. 업스트림 도구 변경을 반영하려면 파사드를 다시 시작하거나(또는 7일 TTL이 지나기를 기다리면) 됩니다.

• discover는 단순한 부분 문자열 일치이며 최대 10건으로 제한됩니다.

• 인증 오류 시 재시도는 한 번만입니다. 그 외 업스트림 오류는 그대로 전파됩니다.

• 업스트림 프롬프트, 리소스, 샘플링을 지원하지 않습니다 — 도구만 지원합니다.