이미 OpenClaw Gateway를 돌리고 있다면 다음 단계는 보통 Model Context Protocol(MCP) 도구를 에이전트 워크플로에 붙이는 일입니다: 저장소 조회, 내부 API 호출, 통제된 명령 실행. 현장에서 마찰은 세 가지로 모입니다—도구 발견·버전 드리프트, 게이트웨이 측 화이트리스트·최소 권한, 그리고 운영에서 흔한 핸드셰이크 실패·타임아웃·자식 프로세스 정지. 본문은 사이트의 설치, 보안 강화, modelRouting, 관측 글과 역할을 나누고, stdio와 원격 MCP 형태 대조, 재현 가능한 여섯 단계 롤아웃 체크리스트, 증상 대조표를 제공해 프로덕션에서 MCP를 감사 가능한 「도구 공급망」으로 다루게 합니다.
MCP는 「도구 호출」을 일회성 스크립트에서 세션마다 재사용되는 능력면으로 끌어올립니다. 도구가 하나 늘어날 때마다 데이터 경로와 자식 프로세스 수명 주기가 한 줄씩 붙습니다. 여전히 「로컬에서만 돌면 된다」로 밀면 게이트웨이에서 곧바로 도구 열거 폭증, 암묵적 업그레이드, 타임아웃 부재, 화이트리스트 부재 네 가지에 부딪힙니다. 아래 일곱 항목은 검토회 자가 점검용이며, 데모 설정을 프로덕션에 그대로 옮기는 것을 막습니다.
세 가지 이상이 「예」이면 MCP를 거버넌스가 있는 공급망으로 봐야 합니다: 명시적 등록, 버전 고정, 관측·롤백이 필요하고, openclaw.json을 초안장으로 쓰면 안 됩니다.
도구 목록이 재시작마다 흔들리는가: 매번 올릴 때 도구 수·이름이 바뀌면 발견 경로가 버전화되지 않았거나 작업 디렉터리가 고정되지 않은 것입니다. 그러면 「오늘 무엇이 열거됐는지」를 추측하는 디버깅이 됩니다.
명시적 화이트리스트가 없는가: 기본 「전부 허용」은 데모에선 빠르지만 프로덕션에선 임의의 프롬프트가 임의의 시스템 능력으로 매핑됩니다. dmPolicy·실행 승인 정책과 함께 검토해야 합니다.
stdio 자식에 하드 타임아웃이 없는가: 무한 대기는 Gateway 스레드·큐를 단 하나의 멈춘 MCP에 잠그고, 「모델은 답하는데 도구는 영원히 안 돌아온다」로 보입니다.
원격 MCP가 아웃바운드 정책을 우회하는가: HTTP/SSE 도구를 networkPolicy 논의 없이 두면 게이트웨이 뒤에 새 출구가 열리고, 보안 강화 글의 가정과 충돌합니다.
비밀이 환경 변수 일괄 주입인가: 토큰을 전역 환경에만 두고 도구 인스턴스를 나누지 않으면 한 번 유출이 모든 MCP로 퍼집니다. 구성 구간을 나누고 로테이션을 지원해야 합니다.
modelRouting과 충돌하는가: 큰 컨텍스트는 고가 모델, 작은 일은 경량 모델로 갈 때 도구 실패 재시도가 서로 다른 모델에서 반복될 수 있어 라우팅층·도구층에서 함께 속도 제한이 필요합니다.
관측이 Gateway만 보는가: 로그에 MCP 자식 기동 인자·종료 코드가 없으면 운영에서는 「재시작해 본다」뿐입니다. 관측 글의 로그 필드와 맞춰야 합니다.
이 신호를 펼치면 핵심은 하나입니다: MCP 연결 = 설정·프로세스·네트워크·권한 네 줄을 동시에 조인다. 다음 표로 stdio와 원격 MCP 차이를 고정한 뒤 여섯 단계 체크리스트로 넘어갑니다.
사이트 글 역할은 이렇게 기억하면 됩니다: 설치·systemd·Docker 글은 「Gateway 프로세스를 어떻게 상시 구동할지」; 보안 강화 글은 「누가 붙을 수 있고 어디로 나갈 수 있는지」; modelRouting 글은 「모델 층·비용」; 본문은 「도구가 어디서 오는지, 어떻게 허용되는지, 어떻게 고칠지」—네 겹이 맞아야 감사 가능한 프로덕션 토폴로지입니다.
이 표는 아키텍처 검토용입니다. 같은 요구도 둘 다 구현할 수 있지만 위협 모델과 장애 양상이 다릅니다. 「설정 두 줄 덜 쓰는 쪽」만 비교하지 마세요.
| 차원 | stdio(본기 자식) | 원격 MCP(HTTP/SSE 등) |
|---|---|---|
| 프로세스 경계 | Gateway와 동일 사용자·동일 호스트, 환경 변수·파일 권한 상속 | 호스트 간, TLS·인증·헬스 체크 별도 |
| 네트워크 노출 | 기본 추가 리스닝 없음; 위험은 로컬 명령·경로 주입 | 새 엔드포인트·아웃바운드 의존, networkPolicy 편입 필요 |
| 업그레이드·재현 | 로컬 바이너리·패키지 버전 의존, 버전·해시 고정 필요 | 중앙 배포 가능하나 롤링·호환 행렬 필요 |
| 전형적 장애 | PATH·권한·인터프리터 불일치로 기동 직후 종료 | DNS, TLS, 리버스 프록시 타임아웃, 401/403 체인 |
| 관측 포인트 | 자식 PID, 종료 코드, stderr 슬라이스 | HTTP 상태, 재시도 곡선, E2E 지연 분위 |
MCP는 「플러그인 하나」가 아니라 실행 가능한 공급망이 한 줄 더 생긴 것입니다. stdio와 원격 중 무엇을 고르느냐는 위험을 본기 경계에 둘지 네트워크 경계에 둘지 고르는 일입니다.
무거운 빌드나 macOS 전용 툴체인을 원격 실행층에 두는 흔한 형태는 Gateway는 Linux/VPS에서 돌고, 독점 원격 Mac이 xcodebuild와 서명 단계를 맡아 통제된 채널로 로그·아티팩트를 돌려보내는 경우입니다. 이때 MCP는 「가벼운 오케스트레이션면」에 두는 편이 낫고, 장시간 작업을 게이트웨이 한 프로세스에 쌓으면 장애 반경이 커집니다. 연산·디스크는 계약 가능한 노드에 두세요.
순서대로 실행해 「도구가 된다」를 「변경이 감사되고 실패가 위치되며 롤백 경로가 있다」로 끌어올립니다.
도구 신원 등록: MCP마다 안정적 이름, 버전 출처(패키지명·커밋·다이제스트), 담당자를 적습니다. 익명 스크립트가 저장소와 함께 떠다니게 두지 마세요.
최소 권한 기동 인자: stdio는 절대 경로·전용 작업 디렉터리; 원격 MCP는 TLS·타임아웃·재시도 상한을 명시하고 암묵적 시스템 프록시에 의존하지 않습니다.
설정 검증: 변경 후 먼저 openclaw config:validate, 이어서 openclaw doctor를 돌리고 오류를 머지 게이트로 취급합니다.
화이트리스트 정합: 허용 도구 집합을 dmPolicy·실행 승인과 교차 검사해 「설정에선 껐는데 모델이 경로를 추측한다」 같은 어긋남을 막습니다.
그레이스 경로: 저트래픽 세션에만 새 도구를 켜고 구 도구를 일주일 병행합니다. 실패율·P95 지연·자식 재기동 횟수를 비교 기록합니다.
롤백 패키지: 이전 openclaw.json과 이미지 다이제스트를 백업합니다. 장애 시 먼저 설정·이미지를 롤백하고 도구 자체는 그다음에 파고듭니다.
{
"mcpServers": {
"internal-git": {
"command": "/opt/mcp/git-mcp",
"args": ["--config", "/etc/mcp/git.prod.json"],
"env": { "MCP_LOG_LEVEL": "info" }
}
}
}
안내: 예시는 구조만 보여 줍니다. 실제 키 이름·중첩은 사용 중인 OpenClaw 버전 문서를 따르세요. 메이저 업그레이드 전에는 스테이징에서 동일한 validate/doctor를 먼저 돌리세요.
보안 강화 글은 리스닝면·토큰·dmPolicy·networkPolicy를 강조합니다. MCP를 붙이면 도구 호출이 새로운 「실행 출구」가 되므로 호출 가능한 도구 집합과 닿을 수 있는 하류를 같은 검토표에 둡니다. 실무에서는 도구 유형마다 최대 동시성·호출당 타임아웃·일일 호출 예산·실패 후 차단 전략을 정의합니다.
「모델이 도구를 쓴다고 하는데 프런트는 계속 돈다」일 때 우선 세 가지를 대조합니다: 자식이 안 떴다(경로·권한), 핸드셰이프가 끝나지 않았다(프로토콜 버전·인증), 하류가 막혔다(네트워크나 비즈 API). 종료 코드·stderr를 모은 채 Gateway만 반복 재시작하지 마세요. 간헐 장애가 상시 사고로 바뀝니다.
관측 글과 맞출 때는 MCP 기동·종료를 같은 로그 상관 ID에 넣어 「모델 요청 → 도구 호출 → 자식 종료」를 한 줄로 잇습니다.
주의: 프로덕션에서 장기간 「디버그 수준 도구 열거 로그」를 비식별 없이 켜 두지 마세요. 도구 인자에는 저장소 경로·내부 호스트명·토큰 조각이 자주 섞입니다.
아래는 당번·사후 복기용입니다. 구체 임계는 자사 SLO·모니터링으로 채우세요.
노트북에만 MCP를 쌓고 게이트웨이 거버넌스·안정 실행 평면이 없으면 절전·디스크·다중 세션 경쟁에서 자주 깨집니다. 무거운 부하를 Gateway 동일 프로세스에 몰아넣어도 장애 반경이 커집니다. 감사 가능한 도구군·안정 디스크·7×24 예측 가능 연산이 필요한 팀에는 OpenClaw Gateway가 세션·정책을, 독점 원격 Mac 노드가 macOS/iOS 빌드·장시간 작업을, MCP는 좁은 인터페이스만 노출하는 조합이 현실적입니다. 도구 거버넌스와 연산 비용을 함께 보면 NodeMini 클라우드 Mac Mini 임대를 실행층 베이스로 두기 적합합니다: 게이트웨이의 MCP 오케스트레이션과 클라우드 Mac의 빌드·서명을 분리하고, 본문 체크리스트로 버전·화이트리스트·타임아웃을 잡으면 됩니다.
먼저 openclaw config:validate, 이어서 openclaw doctor를 권장합니다. 알려진 무효 키를 자동 정리할 때는 doctor --fix를 신중히 쓰고 변경 기록을 남기세요. 연결·주문 관련 질문은 헬프 센터를 참고하세요.
stdio는 동일 호스트·경계 명확에 맞고, HTTP/SSE는 호스트 간에 맞지만 TLS·인증·networkPolicy를 겹쳐야 합니다. OpenClaw 칼럼의 보안 글과 함께 검토하고 단독으로 결정하지 마세요.
Gateway는 대화·도구 정책을 계속 맡고, 무거운 일은 독점 원격 Mac에 둡니다. OpenClaw 분류와 Mac mini 대여 요금을 먼저 보고 도구 오케스트레이션과 연산 노드를 분리해 설계하세요.