MCP CI 게이트에는 증빙이 필요합니다: tools/list만으로는 부족합니다

MCP 서버들이 일반적인 인프라(infrastructure)처럼 보이기 시작했습니다.

그 말은 즉, 지루한 인프라 점검(infrastructure checks)이 필요하다는 뜻입니다.

제가 계속해서 목격한 실수는 다음과 같습니다:

"서버가 시작되고, tools/list가 깨끗한 스키마(schema)를 반환합니다. 그러므로 작동합니다."

그것만으로는 충분하지 않습니다.

MCP 서버가 initialize를 통과하고, 예상되는 모든 도구(tool)를 광고하더라도, 인증(auth), 범위(scopes), 테넌트 경계(tenant boundaries), 환경 변수(environment variables), 다운스트림 권한(downstream permissions), 또는 읽기 전용 역할(read-only roles)이 깨져 있다면 실제 호출(call) 시에는 모두 실패할 수 있습니다.

그래서 저는 mcp-probe@1.8.0을 MCP 서버를 위한 진정한 CI 준비성 게이트(CI readiness gate)에 더 가깝게 밀어붙였습니다.

npx @k08200/mcp-probe@latest --config mcp-probe.config.json --github-summary --fail-on-warn

변경 사항

1. 이제 경고(Warnings)로 CI를 실패시킬 수 있습니다

기본적으로 경고는 여전히 종료 코드 0을 반환합니다. 이는 기존 사용자들이 갑작스러운 CI 실패를 겪지 않도록 하기 위함입니다.

하지만 프로덕션 게이트(production gates)에는 종종 더 엄격한 동작이 필요합니다:

mcp-probe --config mcp-probe.config.json --fail-on-warn

--fail-on-warn을 사용하면, 인증 핸드오프(auth handoff) 문제, 권한 경고, 또는 불완전한 준비성 증빙(readiness receipts)이 워크플로(workflow)를 차단할 수 있습니다.

이것이 중요한 이유는 많은 MCP 실패가 완전한 충돌(hard crashes)이 아니기 때문입니다. 그것들은 성능 저하 상태(degraded states)입니다:

• OAuth 흐름이 에이전트(agent)가 완료할 수 없는 브라우저 리다이렉트(browser redirect)를 요구함
• 서버는 시작되지만 모든 도구 호출(tool call)이 401을 반환함
• 데이터베이스 도구가 관리자 자격 증명(admin credentials)으로는 작동하지만, 의도된 읽기 전용 역할(read-only role)로는 실패함
• 워크플로에서 프로브(probe)를 언급하지만, 실제로 프로덕션 경계 점검(production boundary check)을 실행하지는 않음

2. Doctor가 이제 실제 워크플로 증빙(workflow receipt)을 확인합니다

mcp-probe doctor는 이미 GitHub Actions 워크플로가 존재하는지 확인했습니다.

하지만 그것 역시 충분하지 않습니다.

새로운 동작은 더 엄격합니다: 필수 플래그(flags)가 동일한 실제 mcp-probe 실행 단계(run step)에 나타나야 합니다.

다음은 통과되어야 합니다:

- run: npx @k08200/mcp-probe@latest --config mcp-probe.config.json --github-summary --fail-on-warn

다음은 완전한 게이트로 간주되지 않습니다:

• run: npx @k08200/mcp-probe --config mcp-probe.config.json
• run: npx @k08200/mcp-probe ./server.js --github-summary --fail-on-warn

이 플래그들은 워크플로(workflow) 어딘가에 존재하지만, 단일 실행 단계(run step)만으로는 의도한 설정(config)이 CI 요약(CI summaries) 및 엄격한 경고 처리(strict warning handling)와 함께 실제로 확인되고 있다는 것을 증명하지 못합니다.

이것이 "게이트(gate)가 있다"와 "게이트가 우리가 신뢰하는 사항을 강제(enforcing)하고 있다"의 차이입니다.

3. 도구 호출 커버리지(Tool call coverage)는 이제 예상되는 도구와 연결됩니다

설정 기반 검사(config-based checks)를 위해, 예상되는 도구 카탈로그(tool catalog)를 선언할 수 있습니다:

{
  "servers": [
    {
...

expectedTools와 toolsFile이 모두 설정된 경우, 모든 예상되는 도구에는 사이드카 샘플 입력(sidecar sample input)이 필요합니다.

이는 CI가 단순히 "도구가 광고되고 있는가?"를 확인하는 것이 아니라, "에이전트(agent)가 의존하는 도구에 대해 실제로 의미 있는 드라이런(dry-run) 샘플을 제공했는가?"를 확인함을 의미합니다.

4. 사이드카 입력(Sidecar inputs)이 진정한 계약(contract)입니다

자동 생성된 입력은 스모크 테스트(smoke tests)에는 유용하지만, 대부분 스키마 검증(schema validation) 단계에 머뭅니다.

진정한 준비 상태 확인(readiness checks)에는 의미 있는 입력이 필요합니다:

{
  "tools": {
    "logs_query": {
...

데이터베이스 기반 MCP 서버의 경우, 다음과 같은 단언(assertions)들이 핵심적인 부분입니다:

• 읽기 전용 역할(read-only role)이 작동하는가?
• 행 제한(row limits)이 강제되는가?
• 광범위한 내보내기(exports) 또는 관리자 작업(admin actions)이 부재하거나 차단(gated)되어 있는가?
• 거부된 쓰기(denied writes)가 에이전트가 복구할 수 있을 만큼 충분히 구조화되어 있는가?
• 결과에 출처(source) 및 최신성(freshness)과 같은 출처 정보(provenance) 필드가 포함되어 있는가?
• 응답에서 비밀 정보(secrets), 스택 트레이스(stack traces) 또는 가공되지 않은 내부 정보(raw internals)의 유출을 방지하는가?

설치

npm install -D @k08200/mcp-probe

또는 직접 실행:

npx @k08200/mcp-probe@latest doctor
npx @k08200/mcp-probe@latest --config mcp-probe.config.json --github-summary --fail-on-warn

GitHub: https://github.com/k08200/mcp-probe
npm: https://www.npmjs.com/package/@k08200/mcp-probe

목표는 간단합니다: MCP를 위한 CI는 단순히 프로세스가 시작되는지 여부가 아니라, 에이전트가 실제로 의존하게 될 계약(contract)을 테스트해야 합니다.