APX mcp check는 Shadowed MCP를 디버깅하는 가장 빠른 방법입니다

APC는 휴대 가능한 컨텍스트 레이어 (portable context layer)입니다. APX는 APC를 매일 유용하게 사용할 수 있도록 만드는 로컬 런타임 및 툴링 레이어 (local runtime and tooling layer)입니다. MCP 설정이 잘못된 것처럼 느껴질 때, 가장 빠른 해결 방법은 대개 최종 서버 목록을 뚫어지게 쳐다보는 것이 아닙니다. APX가 소스들을 어떻게 병합 (merge)했는지 검사하는 것입니다.

그것이 바로 apx mcp check가 중요한 이유입니다. 이 명령은 소스 파일, 병합 후의 활성 엔트리 (active entries), 그리고 모든 충돌 (conflicts)을 보여줍니다. 다시 말해, 이 명령은 실제 질문에 답을 해줍니다: 어떤 MCP가 승리했으며, 무엇이 섀도잉 (shadowed) 되었는가?

list만으로는 부족한 이유

apx mcp list는 유용하지만, 병합된 결과만을 보여줍니다. 이는 빠른 인벤토리 (inventory) 확인에는 좋지만, 드리프트 (drift)를 디버깅하는 데는 좋지 않습니다. 만약 동일한 MCP 이름이 하나 이상의 스코프 (scope)에 존재한다면, 최종 목록은 해당 이름을 생성한 경로를 숨겨버립니다.

깔끔한 목록이라도 여전히 잘못된 설정을 숨길 수 있습니다. 예를 들어:

• .apc/mcps.json에 있는 공유 (shared) MCP
• ~/.apx/projects/<id>/mcps.json에 있는 런타임 오버라이드 (runtime override)
• ~/.apx/mcps.json에 있는 머신 와이드 (machine-wide) 엔트리

이름은 멀쩡해 보일 수 있습니다. 하지만 소스는 당신이 예상했던 것이 아닐 수 있습니다.

병합 규칙 (The merge rule)

APX는 우선순위에 대해 명시적입니다: runtime > shared > global. 이름이 충돌할 경우 런타임 파일이 승리하며, 그다음은 공유 APC 파일, 마지막으로 머신 와이드 글로벌 파일 순입니다. 테스트는 이 체인을 다루고 있으며, CLI는 의도적으로 충돌을 출력합니다.

이는 두 가지를 의미합니다:

1. 섀도잉 (Shadowing)은 정상적인 현상입니다.
2. 섀도잉은 눈에 보여야 합니다.

만약 서버가 사라지거나 예상과 다르게 동작한다면, 추측하지 마세요. APX에게 어떤 소스가 승리했는지 물어보세요.

mcp check가 보여주는 것

apx mcp check는 세 가지 유용한 뷰 (views)를 동시에 제공합니다:

• 소스 파일 및 각 파일의 존재 여부
• 병합 후의 활성 엔트리 (active entries)
• 이름이 두 번 이상 나타날 경우의 충돌 (conflicts)

이것이 디버깅을 위한 적절한 수준입니다. 이는 APX가 레포 (repo) 파일, 런타임 파일, 또는 글로벌 파일을 읽고 있는지 알려줍니다. 또한 특정 엔트리가 APX 소유인지, 아니면 APX가 권고 사항으로만 읽어들이는 외부 IDE 설정에서 온 것인지도 알려줍니다.

전형적인 흐름은 다음과 같습니다:

apx mcp check --project iacrmar
apx mcp list --scope runtime --project iacrmar
apx mcp list --scope shared --project iacrmar

먼저 check를 사용하세요. list는 어디를 살펴봐야 할지 이미 알고 있을 때 두 번째로 사용합니다.

구체적인 실패 사례

저장소(repo)의 모든 클론(clone)이 해당 서버의 존재를 알 수 있도록 공유 범위(shared scope)에 github를 추가했다고 가정해 봅시다. 나중에 이 머신에 토큰이 필요하여 런타임 범위(runtime scope)에 또 다른 github 항목을 추가합니다.

이것은 버그가 아닙니다. 계층적 오버라이드 (layered override)입니다. 하지만 런타임 복사본이 존재한다는 사실을 잊어버린다면, 공유 파일을 수정하더라도 여전히 런타임 버전이 승리하는 것을 보게 될 수 있습니다. APX가 병합 규칙 (merge rule)에 따라 동작하고 있기 때문에 프로젝트는 변경되지 않은 것처럼 보입니다.

apx mcp check는 이 상황을 명확하게 보여줍니다. 런타임 항목을 승자(winner)로 표시하고, 공유 항목을 패자(loser)로 보고합니다.

소유권은 여전히 중요합니다

APX는 다른 도구에서 온 외부 MCP 설정(foreign MCP configs)을 검사할 수는 있지만, 이를 다시 작성(rewrite)하지는 않습니다. 이 부분의 코드는 매우 신중하게 설계되었습니다. 만약 MCP가 외부 소스에서 온 것이라면, APX는 대신 해당 도구의 설정에서 변경하라고 알려줍니다. 이는 훌륭한 경계 설정입니다. APX는 APX가 소유한 범위(scopes)를 관리해야 하며, 타인의 설정을 조용히 변형(mutate)해서는 안 됩니다.

따라서 실질적인 규칙은 간단합니다:

• 저장소 공유 (repo-shared) MCP는 APC에 속해야 합니다.
• 머신 특정 (machine-specific) MCP는 APX 런타임 (runtime)에 속해야 합니다.
• 머신 전체 기본값 (machine-wide defaults)은 APX 글로벌 (global)에 속해야 합니다.
• 외부 IDE 설정은 IDE에 그대로 유지됩니다.

이러한 분리가 APC에도 도움이 되는 이유

APC는 이야기의 공유된 부분만 담고 있기 때문에 이식성 (portable)을 유지할 수 있습니다. 만약 토큰이나 로컬 엔드포인트 (local endpoint)가 저장소에 몰래 포함된다면, 클론 안전 계약 (clone-safe contract)이 깨지게 됩니다. APX는 런타임 상태를 로컬에 유지하고 충돌을 숨기는 대신 가시화함으로써 그 계약을 보호합니다.

이것이 mcp check가 존재하는 더 깊은 이유입니다. 이것은 단순한 상태 화면이 아닙니다. 이식 가능한 컨텍스트 (portable context)와 로컬 실행 (local execution) 사이의 경계를 확인하는 건전성 검사 (sanity check)입니다.

결론

MCP 동작이 잘못된 것처럼 보인다면, apx mcp check부터 시작하세요.

이 명령은 파일, 승자(winners), 그리고 충돌(conflicts)을 보여줍니다. 이는 어떤 레이어가 승리했는지 또는 어떤 파일이 섀도잉(shadowed)되었는지 추측할 필요 없이, 단 한 번의 실행만으로 문제를 설명하기에 대개 충분합니다.