MCP 서버를 OpenClaw에 붙이는 법｜stdio·HTTP 전송 방식과 도구 필터·승인 규칙

AI 에이전트를 쓰다 보면 "이 도구만 있으면 되는데"라는 순간이 옵니다. 사내 문서 검색, 파일 시스템 접근, 특정 SaaS 조회 같은 것들이요. 이걸 매번 직접 구현하지 않고 남이 만들어 둔 것을 빌려 쓰는 규약이 MCP(Model Context Protocol)입니다.

OpenClaw 공식 문서는 MCP를 "에이전트가 다른 프로그램의 도구를 빌리는 방법"으로 설명합니다. MCP 서버가 도구·리소스·프롬프트를 노출하면, OpenClaw가 거기에 연결해 내 에이전트가 그 도구를 쓸 수 있게 해 주는 구조입니다. 이 글은 공식 문서 Connect MCP servers(tools/mcp)와 MCP CLI reference(cli/mcp)를 한국어 독자 기준으로 정리한 것입니다.

먼저 방향부터 가른다

MCP 이야기가 헷갈리는 이유는 방향이 두 개이기 때문입니다. 문서도 이 둘을 명확히 분리합니다.

• 바깥 → OpenClaw로 도구를 들여오기. 서드파티 MCP 서버를 mcp.servers에 등록해 내 에이전트가 쓰게 하는 쪽입니다. 이 글의 주제고, OpenClaw는 여기서 MCP 클라이언트 역할을 합니다.
• OpenClaw → 바깥으로 대화를 노출하기. openclaw mcp serve로 OpenClaw 자체가 MCP 서버가 되어, Codex나 Claude Code 같은 외부 MCP 클라이언트가 채널 대화를 읽고 보내게 하는 쪽입니다.

같은 openclaw mcp 명령 아래 있지만 하는 일이 정반대라, 문서도 "어느 쪽이 필요한지 모르겠으면 openclaw mcp status --verbose부터 보라"고 안내합니다. 이 명령은 저장된 내용만 보여 주고 MCP 서버를 실제로 띄우지 않습니다.

서버를 붙이는 세 가지 경로

1) Control UI 설정에서

Control UI에서 Settings → MCP로 들어가 Configured servers → Add server를 고릅니다. 고유한 이름을 정하고 전송 방식으로 Streamable HTTP, SSE, Stdio 중 하나를 선택합니다. HTTP 계열이면 서버의 http://·https:// 주소를, stdio면 실행할 명령과 인자를 넣습니다.

헤더, 환경 변수, OAuth 메타데이터, TLS, 타임아웃, 도구 필터처럼 기본 항목을 넘어가는 설정은 같은 페이지 아래쪽의 스코프 설정 편집기에서 다룹니다. 서버 행에서 사용·중지·삭제도 가능합니다.

2) 채팅 컴포저에서

Control UI 대화창에서 + → Connectors → Add MCP server…로도 추가할 수 있습니다. 관리자 권한이 필요하고, This session(이 세션만)과 Everywhere(전역) 중에서 고릅니다. 다만 어느 쪽을 골라도 서버 정의 자체는 전역으로 저장되고, 세션 단위는 그 위에 얹히는 정책 층이라는 점이 문서에 명시돼 있습니다.

진행 중인 대화에서 + → Connectors → Tool access를 열면 개별 도구를 세션 단위로 확인하거나 차단할 수 있습니다.

3) CLI에서

로컬 stdio 서버를 붙이는 예시입니다.

openclaw mcp add local-tools \
  --command node \
  --arg ./dist/mcp-server.js \
  --cwd /srv/openclaw-tools
openclaw mcp doctor local-tools --probe

원격 Streamable HTTP 서버에서 일부 도구만 가져오는 예시입니다.

openclaw mcp add docs \
  --url https://mcp.example.com/mcp \
  --transport streamable-http \
  --include 'search,read_*'
openclaw mcp doctor docs --probe

저장했다는 것은 연결됐다는 뜻이 아니다

여기가 실무에서 제일 자주 걸리는 지점입니다. 문서는 "정의를 저장한 것은 도달 가능성을 전혀 증명하지 않는다. 증명하는 것은 probe다"라고 못 박습니다. 그래서 추가 직후 항상 이 명령이 따라붙습니다.

openclaw mcp doctor <name> --probe

doctor는 먼저 저장된 정의를 검증하고, 그다음 실제 연결을 열어 서버가 광고하는 도구와 기타 기능을 보고합니다. 설정만 보는 요약은 openclaw mcp status --verbose, 살아 있는 기능 확인은 openclaw mcp probe <name>, OAuth를 쓰는 HTTP 서버 로그인은 openclaw mcp login <name>입니다.

설정 파일로 직접 쓸 때

{
  mcp: {
    servers: {
      docs: {
        url: "https://mcp.example.com/mcp",
        transport: "streamable-http",
        enabled: true,
        connectionTimeoutMs: 5000,
        requestTimeoutMs: 20000,
        toolFilter: {
          include: ["search", "read_*"],
        },
      },
    },
  },
}

문서가 짚는 제약이 몇 가지 있습니다.

• 활성화된 서버에는 command(stdio) 또는 URL(SSE·Streamable HTTP) 중 하나가 반드시 있어야 합니다.
• 서버 이름으로 __proto__는 예약어라 쓸 수 없습니다.
• enabled: false로 두면 정의는 남기고 연결만 끊어 둡니다.
• 자격 증명은 설정 리터럴에 적지 않습니다. 민감한 헤더·환경 값은 지원되는 시크릿 메커니즘으로 보관하라고 문서가 명시합니다.

게이트웨이 핫 리로드가 켜져 있으면 바뀌거나 삭제된 서버는 즉시 퇴역하고 다음 턴의 도구 탐색부터 새 정의를 씁니다. 반대로 바뀌지 않은 서버는 진행 중인 실행을 포함해 연결과 캐시된 도구 목록을 그대로 유지합니다.

연결한다고 정책이 풀리지는 않는다

보안 관점에서 가장 중요한 문장은 이겁니다. MCP 서버가 노출한 도구도 다른 모든 도구와 똑같이 도구 프로필·도구 정책 통제를 거치며, 서버를 연결했다고 해서 정책을 우회하지 않습니다. 도구가 막히는 층위를 구분하는 방법은 OpenClaw 도구가 막힐 때｜샌드박스·도구 정책·Elevated 권한을 구분하는 법에서 다룬 적이 있습니다.

승인 동작은 세션 권한 태세를 따릅니다. 기본값인 전체 권한 태세에서는 묻지 않고, 더 엄격한 모드에서는 안전 주석이 없는 도구를 검사합니다(workspace는 자동 검토, guarded·read-only는 운영자에게 질의 가능).

지속 저장이 제공되는 경우 Allow Always는 "그 서버의 그 도구"에 대한 에이전트 단위 승인을 저장합니다. 인자가 바뀌어도 유지되고 재시작 후에도 살아남습니다. 다만 적용 시점은 다음 스레드 설정·훅 등록 시점(새 세션이나 재시작)이고, 현재 세션은 Codex가 기억한 결정을 씁니다. 서버별로 강제하려면 openclaw mcp configure <server> --approval approve|prompt|auto를 쓰며, 명시적 모드가 태세 기반 기본값보다 우선합니다. 저장된 승인은 auto이거나 모드가 지정되지 않았을 때만 적용되고, 명시적 prompt는 계속 묻습니다.

안 될 때 보는 순서

설정에는 보이는데 도구가 하나도 없다

openclaw mcp doctor <name> --probe를 돌립니다. 연결은 되는데 기대한 도구가 없다면 toolFilter.include와 toolFilter.exclude를 확인합니다. 필터를 좁게 걸어 두고 잊는 경우가 흔합니다.

stdio 서버가 안 뜬다

command가 게이트웨이 프로세스의 환경에서 해석되는지, cwd가 실제로 존재하는지 확인합니다. 내 터미널에서 되는 것과 게이트웨이에서 되는 것은 다릅니다. 인자는 args에 넣어야 하고, transport: "stdio"를 명시했다면 command가 비어 있으면 안 됩니다. 디버그 로그에서 stderr 진단은 bundle-mcp:<name>: 접두사로 찍힙니다.

HTTP 서버가 인증을 요구한다

auth: "oauth"와 필요한 oauth 메타데이터를 설정한 뒤 openclaw mcp login <name>을 실행하고 출력된 인증 URL을 따라갑니다. 보통 OpenClaw가 루프백 리다이렉트를 받아 자격 증명을 자동 저장하지만, 브라우저가 콜백 리스너에 닿을 수 없는 환경이면 출력된 --code 명령을 씁니다.

바꿨는데 에이전트에 반영이 안 된다

openclaw mcp reload는 현재 CLI 프로세스가 소유한 런타임만 갱신합니다. 다른 곳에서 돌고 있는 게이트웨이나 에이전트는 그쪽에서 별도로 리로드하거나 설정을 배포하거나 재시작해야 합니다.

정리

MCP를 붙이는 일은 결국 네 단계입니다. ① 방향(클라이언트냐 serve냐)을 먼저 가르고, ② 전송 방식에 맞게 등록하고, ③ doctor --probe로 실제 연결을 증명하고, ④ 도구 정책과 승인 태세 안에서 쓰는 것. 특히 ③을 건너뛰면 "설정은 다 했는데 에이전트가 도구를 못 본다"는 상황에서 한참을 헤매게 됩니다.

에이전트가 도구를 어떻게 나눠 갖는지는 OpenClaw 서브에이전트란? 일을 나눠 맡길 때 권한·깊이·보고가 정해지는 규칙에서, OpenClaw 전체 구조는 OpenClaw란? 카톡·텔레그램으로 AI 에이전트를 부리는 셀프호스팅 게이트웨이에서 이어서 보시면 됩니다.

출처: OpenClaw 공식 문서 docs.openclaw.ai 의 Connect MCP servers(tools/mcp) 및 MCP CLI reference(cli/mcp). 이 글은 공식 문서를 한국어 독자 기준으로 정리한 설명이며, 특정 MCP 서버에 대한 개인 사용 후기나 성능 측정 결과는 포함하지 않습니다.