OpenClaw Gateway를 가동한 뒤 MCP 도구군을 붙일 때 난관은 흔히 「핑이 된다」가 아니라 전송 형태 선택, 자식 프로세스 수명 주기, 핸드셰이크 프로토콜, 다운스트림 정지(Hang)에 있습니다. 본문은 사이트의 MCP 화이트리스트·연결성, 보안 강화, 크로스플랫폼 설치 글과 역할을 나눕니다. 먼저 범위와 일곱 가지 자가 점검 포인트를 제시하고, stdio와 HTTP/SSE 대조표로 아키텍처를 정한 뒤 재현 가능한 일곱 단계 연동, 도구 발견·버전 드리프트 주의사항, 증상→조치 빠른 참조로 MCP를 임시 스크립트가 아니라 감사 가능한 공급망으로 다루도록 돕습니다.
설치 글은 Gateway 프로세스를 어떻게 상시 실행할지 다루고, 보안 글은 리스닝 면, 토큰, dmPolicy와 이그레스를 다루며, 화이트리스트 글은 도구 등록과 권한 거부 시 첫 대응을 다룹니다. 본문은 그 다음 단계로, stdio 자식 프로세스와 HTTP 원격 MCP의 운영 차이, 그리고 핸드셰이크·타임아웃·정지 시 어떤 로그를 봐야 하는지에 초점을 맞춥니다.
아래 일곱 항목 중 세 가지 이상이 해당되면 검토서에 「MCP 런타임」 위험을 별도 행으로 두는 편이 좋습니다. 「Gateway만 재시작해 본다」는 포괄 항목에 흡수하지 않는 것이 좋습니다.
명령행이 개발기에서만 성립합니다: npx 경로, Node 마이너 버전, 전역 패키지가 systemd 환경과 대화형 셸에서 달라 「SSH로는 되는데 Gateway가 띄우면 실패」하는 경우입니다.
작업 디렉터리에 숨은 의존성이 있습니다: MCP 자식이 특정 저장소 루트에서 뜬다고 가정하는데, 빈 HOME이나 읽기 전용 마운트로 바뀌면 조용히 실패합니다.
HTTP MCP는 URL만 보고 TLS를 놓칩니다: 인증서 체인, SNI, 사내 자체 서명과 networkPolicy 조합이 어긋나면 「끝없는 핸드셰이크」처럼 보일 수 있습니다.
도구 목록 캐시가 낡았습니다: 서버에서 도구를 바꾼 뒤에도 클라이언트가 옛 schema로 호출해 매개변수 검증이 무작위로 깨집니다.
타임아웃 없는 장시간 호출입니다: 다운스트림 API가 멈추면 Gateway 쪽 스레드나 연결이 풀리지 않아 전역 정지로 번집니다.
자식 프로세스가 좀비화합니다: stdio 파이프 한쪽이 잘못 닫히면 프로세스는 살아 있으나 읽고 쓰지 않아 fd와 CPU를 공회전으로 씁니다.
설정 드리프트에 서명이 없습니다: openclaw.json을 여러 대에서 각각 고치고 validate·doctor 기록이 없으면 구두로만 장애 대응하게 됩니다.
이 항목들을 런북에 넣으면 MCP도 CI처럼 「변경 요청 + 롤백 버전」을 갖출 수 있습니다. 이어지는 표로 stdio와 HTTP의 운영 부담을 한눈에 맞춰, 회의에서 「원격이 편하다」 한 마디로 TLS와 이그레스 거버넌스를 건너뛰지 않도록 합니다.
2026년에 흔한 플랫폼 엔지니어링에서는 도구 거버넌스가 「누가 프로덕션에서 자식 프로세스를 띄울 수 있는가」와 묶입니다. stdio는 경계를 OS 사용자와 파일 권한에 두고, HTTP는 경계를 네트워크 정책과 신원 토큰에 둡니다. 우열이 있는 것이 아니라 기존 관측·당번 모델과 맞는지가 문제입니다.
이 표는 SRE·보안·업무 측과 맞출 때 씁니다. 지연만 비교하지 말고 신원, 이그레스, 업그레이드, 장애 격리를 함께 계산합니다.
| 차원 | stdio(로컬 자식 프로세스) | HTTP/SSE 계열 원격 MCP |
|---|---|---|
| 전형적 배치 | Gateway와 동일 호스트 또는 동일 컨테이너 네임스페이스 | 독립 서비스, 사이드카, 사내 클러스터 |
| 신뢰·신원 | OS 사용자, 파일 권한, 선택적 샌드박스 | mTLS, Bearer, 리버스 프록시 인증 |
| 업그레이드 경로 | 이미지·패키지 버전 고정, Gateway 또는 자식 패키지 롤링 | 독립 블루그린, 프로토콜 버전 협상 주의 |
| 관측 포인트 | 종료 코드, stderr, fd 누수, OOM | HTTP 5xx/429, 커넥션 풀, TLS 핸드셰이크 지연 |
| 실패 격리 | 프로세스 크래시는 supervisor 재시작으로 복구 | 네트워크 분할이 여러 도구를 느리게 할 수 있어 차단기가 필요합니다 |
MCP를 땅에 붙인다는 것은 도구 호출을 버전·경계·롤백이 있는 공급망으로 만든다는 뜻이며, 전송 방식은 복잡도를 커널 쪽에 둘지 네트워크 쪽에 둘지만 가릅니다.
보안 강화로 networkPolicy를 이미 좁혔다면 HTTP MCP를 도입할 때 이그레스 화이트리스트를 다시 통과시켜야 합니다. stdio라면 Gateway 실행 사용자가 기대한 바이너리를 실행할 수 있는지 재확인하고, 「편의상 chmod +x를 전 세계에」 같은 우회는 피합니다.
아래는 이미 기동 가능한 Gateway가 있다고 가정합니다. 설치와 데몬이 남았다면 크로스플랫폼 설치 글과 systemd·Docker 프로덕션 글부터 진행합니다.
런타임을 고정합니다: Node 마이너 버전, 패키지 매니저, MCP 서버 패키지 버전을 기록합니다. 프로덕션과 스테이징은 동일 출처여야 합니다.
최소 stdio 프로브: 비대화형 명령으로 Gateway와 동일 사용자에서 MCP를 한 번 수동 기동해 PATH와 cwd를 확인합니다.
설정 조각을 기록합니다: openclaw.json(또는 프로젝트 문서의 설정 파일)에 server를 등록하고, 팀 접두사로 이름 충돌을 막습니다.
검증 체인을 탑니다: 먼저 openclaw config:validate, 이어서 openclaw doctor를 실행합니다. 차이는 변경 요청에 남깁니다.
화이트리스트를 맞춥니다: 화이트리스트 글에 따라 도구 이름과 네임스페이스를 최소 집합으로 조입니다.
관측 훅을 둡니다: 자식 프로세스 CPU·메모리와 HTTP MCP P95 지연에 임계값을 두고 기존 로그 파이프라인에 붙입니다.
롤백을 연습합니다: 직전에 쓰던 설정과 이미지 digest를 보존해 「MCP 설정 한 줄 삭제」로 기준선으로 돌아갈 수 있게 합니다.
{
"mcpServers": {
"corp-files-stdio": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/var/lib/openclaw/mcp-data"],
"env": { "NODE_OPTIONS": "--max-old-space-size=512" }
},
"internal-api-http": {
"url": "https://mcp.internal.example/sse",
"headers": { "Authorization": "Bearer ${MCP_SERVICE_TOKEN}" }
}
}
}
알림: 실제 키 이름과 중첩 경로는 사용 중인 OpenClaw 버전 문서를 따릅니다. 위 예는 stdio와 HTTP 두 입구가 공존할 때의 구조만 보여 줍니다. 메이저 업그레이드 전에는 validate를 다시 돌리고 릴리스 노트의 호환성 깨짐을 대조합니다.
MCP 도구 이름은 게이트웨이 쪽에서 네임스페이스가 붙는 경우가 많습니다. 여러 환경이 같은 Gateway를 쓰면 「같은 이름, 다른 구현」 호출 사고가 납니다. 설정에 접두사(예: prod_/stg_)를 명시하고, 배포 목록에 이번에 바뀐 도구 목록 diff를 적습니다.
HTTP MCP를 롤링 업그레이드할 때는 하위 호환 schema를 우선 보장합니다. 호환을 깨야 하면 Gateway 허용 목록을 함께 갱신하고 세션 트래픽 일부만 회색으로 돌립니다. stdio 계열 서버 업그레이드에서는 바이너리 ABI와 동적 링커 경로를 보고, 특히 슬림 컨테이너 이미지에서 주의합니다.
주의: 프로덕션 Gateway에서 잠금 없는 npx -y로 최신 패키지를 바로 쓰지 마십시오. digest 고정이나 내부 아티팩트 저장소로 바꾸지 않으면 공급망 감사가 끊깁니다.
아래 증상 표는 온콜 첫 화면용입니다. 세부는 Gateway 로그와 상위 MCP 구현 문서와 함께 봅니다.
| 현상 | 우선 확인 | 흔한 조치 |
|---|---|---|
| 핸드셰이크가 즉시 실패 | 버전 필드, 인증 헤더, TLS 체인 | 프로토콜 버전 맞춤, 인증서 수정 또는 SNI 허용 |
| 첫 성공 이후 더 이상 호출 불가 | 커넥션 풀 고갈, 자식 프로세스 정지 | MCP 쪽 재시작, 타임아웃·차단기 추가 |
| 도구 목록에 항목 누락 | 캐시, 회색 라우팅, 화이트리스트 | 캐시 비우기, allowlist·라우팅 규칙 대조 |
| 무작위 타임아웃 | 다운스트림 API, 쿼터, DNS | 계층적 타임아웃, trace id 출력 |
openclaw.json을 바꿀 때마다 티켓에 검증 명령 출력 일부를 남겨 사후 복기에 씁니다.MCP를 개발용 노트북에만 얹으면 절전, VPN 변동, 다중 데스크톱 세션에서 도구가 간헐적으로 죽습니다. HTTP MCP를 TLS·정책 없이 공개망에 내놓으면 Gateway 공격면이 배로 커집니다. 팀이 안정적인 macOS 환경에서 Apple 도구체인과 연계한 자동화(모바일 빌드·서명·로컬 에이전트와 결합한 MCP 등)를 돌려야 한다면 실행층을 계약된 원격 Mac 노드에 두는 편이 개인 기기 혼용보다 권한·로그 경계를 잡기 쉽습니다. 전송 선택, 자식 프로세스 거버넌스, 당번 모델을 함께 보면 NodeMini Mac Mini 클라우드 임대는 보조 연산 평면으로 맞습니다. OpenClaw 칼럼의 설치·보안·관측 글과 묶어 「모델 게이트웨이 + 도구군 + macOS 실행」 책임층을 나누어 설계할 수 있습니다.
먼저 Gateway와 자식이 동일 사용자인지, PATH·작업 디렉터리·실행 권한이 맞는지 봅니다. 이어서 OOM, OS 강제 종료, npm/npx 캐시를 점검합니다. 연산 용량과 접속 기준선은 Mac Mini 대여 요금과 클라우드 Mac 헬프 센터를 함께 참고합니다.
화이트리스트 글은 등록·권한·연결 실패의 첫 대응에 가깝고, 본 글은 stdio/HTTP 선택, 수명 주기, 정지에 가깝습니다. 검토 회의에서 두 표를 함께 통과시키는 것을 권장합니다.
블로그 OpenClaw 카테고리에서 설치, systemd, Docker, 보안, 관측 글로 들어간 뒤, 필요하면 본문으로 돌아와 MCP 런타임을 세분화합니다.