APC MCP Hints는 비밀(Secrets)을 저장하는 것이 아니라 이름을 명시해야 합니다

프로젝트는 도구(tools)에게 어떤 MCP 서버를 기대하는지 알려줄 수 있습니다.

그것이 저장소(repository)가 자격 증명(credentials)을 보유해야 한다는 의미는 아닙니다.

이것은 APC와 APX 경계 중 가장 명확한 부분 중 하나입니다: APC는 MCP 계약(contract)의 이름을 명시해야 하며, APX는 런타임(runtime) 시점에 비밀(secrets)을 공급하고 사용해야 합니다.

APC는 휴대 가능한 컨텍스트 계층(portable context layer)입니다. 이는 저장소에 프로젝트 소유의 에이전트 컨텍스트(agent context), 규칙(rules), 기술(skills), 그리고 MCP 기대 사항을 선언할 수 있는 하나의 안정적인 장소를 제공합니다. MCP의 경우, 그 장소는 .apc/mcps.json입니다.

APX는 일상적인 사용을 위한 런타임 및 툴링 계층(runtime and tooling layer)입니다. 이는 APC 파일을 읽고, 이를 로컬 런타임 설정(local runtime config)과 병합하며, 충돌을 감사(audit)하고, 서버를 시작하며, apx mcp list, apx mcp run, apx mcp check와 같은 명령어를 통해 도구를 노출합니다.

이러한 역할들을 분리하고 나면, 규칙은 단순해집니다:

.apc/mcps.json은 프로젝트가 무엇을 기대하는지를 기술해야 합니다.
그 기대 사항을 충족하는 데 필요한 비밀(secret) 값들을 포함해서는 안 됩니다.

.apc/mcps.json에 포함되어야 할 것

APC MCP 설정 사양(config spec)은 허용되는 콘텐츠에 대해 구체적으로 정의하고 있습니다. 이 파일에는 다음을 포함할 수 있습니다:

• 서버 이름(server names)
• 명령어(commands) 및 비밀이 아닌 인자(non-secret arguments)
• 엔드포인트 자체가 프로젝트 계약(project contract)의 일부인 경우의 원격 MCP URL
• 사용자가 로컬에서 반드시 제공해야 하는 환경 변수 이름(environment variable names)
• 소비자(consumer)가 지원하는 경우의 활성화 또는 비활성화 상태

이러한 특성이 파일을 휴대 가능하고 검토 가능하게 만듭니다.

저장소는 누군가의 계정이나 머신 로컬 상태(machine-local state)를 유출하지 않고도, "이 프로젝트는 GitHub MCP 서버를 기대합니다" 또는 "이 프로젝트는 여기에 루트를 둔 파일 시스템(filesystem) MCP를 사용합니다"라고 말할 수 있습니다.

안전한 예시는 다음과 같습니다:

{
  "mcpServers": {
    "github": {
...

이는 모든 호환 가능한 소비자에게 무엇을 연결해야 하는지 알려주지만, 실제 자격 증명(credential)은 저장소 외부에 남겨둡니다.

제외되어야 할 것

동일한 APC 사양은 안전하지 않은 콘텐츠에 대해서도 엄격한 선을 긋습니다. 다음을 커밋하지 마십시오:

• API 키 (API keys)
• 베어러 토큰 (bearer tokens)
• OAuth 리프레시 토큰 (OAuth refresh tokens)
• 개인 계정 ID (personal account IDs)
• 프라이빗 헤더 (private headers)
• URL에 포함된 자격 증명 (credentials embedded in URLs)
• 생성된 세션 ID (generated session IDs)
• 경로 자체가 의도적으로 계약 (contract)의 일부가 아닌 한, 로컬 머신의 절대 경로 (machine-local absolute paths)

그 이유는 단순한 비밀 정보 위생 (secret hygiene) 문제보다 더 큽니다.

만약 저장소(repository)가 .apc/mcps.json 파일에 실제 자격 증명을 저장한다면, APC는 휴대 가능한 컨텍스트 (portable context)로서의 역할을 상실하고 프라이빗 런타임 덤프 (private runtime dump)가 되어버립니다. 이는 APC의 존재 목적 자체를 무너뜨립니다.

클론 안전한 계약 (clone-safe contract)은 새로운 노트북, 새로운 팀원, 또는 다른 호환 가능한 런타임 (runtime) 환경에서도 유지되어야 합니다. 실제 토큰은 이러한 경계들을 안전하게 넘어다닐 수 없습니다.

APX가 적합한 위치

이 지점이 바로 APX가 중복되는 도구가 아닌 유용한 도구가 되는 지점입니다.

APX는 APC가 비밀 정보 자체를 보유할 필요가 없습니다. APX는 APC가 휴대 가능한 힌트 (portable hint)를 보유하기를 원합니다. 그러면 APX는 해당 힌트를 로컬 런타임 상태 (local runtime state)와 병합하여 운영 작업을 수행할 수 있습니다.

이것이 바로 APX CLI에 전용 MCP 레이어가 있는 이유입니다:

apx mcp list
apx mcp check
apx mcp run github search_repositories '{"query":"org:agentprojectcontext"}'

여기서 apx mcp check는 특히 관련성이 높은데, 이는 MCP 소스 파일, 병합 순서(merge order), 그리고 충돌(conflicts)을 감사(audit)하기 때문입니다. 실제로 이는 APC가 커밋 안전성 (commit-safe)을 유지하는 동안, APX가 로컬 머신이 누락된 구성 요소들을 올바르게 제공했는지 검증할 수 있음을 의미합니다.

따라서 워크플로우는 다음과 같이 깔끔해집니다:

1. 저장소는 .apc/mcps.json에 예상되는 MCP 서버를 선언합니다.
2. 사용자는 환경 변수 (environment variables) 또는 런타임 소유의 설정 (runtime-owned config)을 통해 로컬에서 자격 증명을 제공합니다.
3. APX는 두 레이어를 모두 읽고, 이를 감사한 뒤 서버를 실행합니다.

이는 모든 것을 하나의 파일에 밀어 넣는 것보다 더 나은 분리 방식입니다.

환경 변수 이름을 지정하는 것만으로 충분한 이유

팀들은 때때로 저장소에 이미 GITHUB_TOKEN과 같은 비밀 정보의 이름이 명시되어 있다면, 그 값도 함께 붙여넣어도 된다고 가정하곤 합니다.

그것은 잘못된 결론입니다.

변수의 이름을 지정하는 것만으로도 충분한 이유는, 소유권을 하드코딩하지 않으면서도 계약 (contract)을 보존할 수 있기 때문입니다.

프로젝트는 다음과 같이 말할 수 있습니다:

• 어떤 변수가 존재해야 하는지
• 어떤 서버가 이를 소비하는지
• 어떤 명령어가 해당 서버를 사용하는지

그러면서도 각 개발자, CI 러너(CI runner), 또는 로컬 데몬(local daemon)이 자신만의 안전한 방식으로 값을 제공할 수 있도록 합니다.

이것이 바로 이식 가능한 컨텍스트 (portable context)가 동작해야 하는 방식입니다.

APC는 공유된 프로젝트의 기대 사항을 Git에 가시적으로 유지합니다.
APX는 런타임 자격 증명 (runtime credentials)과 실행을 로컬에 유지합니다.

작은 규칙이지만, 큰 보상이 따릅니다.

.apc/mcps.json이 비밀 (secrets)을 저장하는 대신 이름을 명시할 때, 저장소는 이식성을 유지하고, 리뷰는 합리적인 수준을 유지하며, APX와 같은 런타임은 프로젝트에 개인적인 상태를 유출하지 않고도 전체 MCP 스택을 여전히 연결할 수 있습니다.