Claude를 사내 시스템에 안전하게 연결하기

사내 서비스에 Claude를 연결하는 프로토타입은 한 가지만 답하면 됩니다 — 연결이 되는가. 실서비스로 올라가는 엔터프라이즈 연동은 여기에 몇 가지 질문을 더 답해 둘 필요가 있습니다.

모델이 누구의 신원으로 동작하고 있고, 그 신원을 나중에 확인(감사)할 수 있는가? 모델이 어떤 데이터에 접근할 수 있고, 그 데이터가 조직 밖으로 나가는 지점은 어디인가? 개별 개발자가 인증 설정을 바꾸지 못하도록 관리자가 설정을 잠글 수 있는가? 그리고 접근을 규제 감사에 쓸 수 있는 형태로 기록할 수 있는가?

이 질문들은 엔터프라이즈 소프트웨어에서 새로운 것이 아닙니다. 규제 데이터를 다루는 외부 시스템이라면 어디에나 적용되는 신원·접근·규정 준수 요건과 같습니다. 이것을 연동 설계의 일부로 처음부터 다루는 것이, 데모와 배포 가능한 결과물을 가르는 지점입니다.

어떤 인증 방식이 맞는지는 그 서비스가 어디서 실행되고 어떤 신원 모델을 쓰는지에 따라 달라집니다. 크게 세 가지 경우로 나눠 볼 수 있습니다.

• 사용자 신원 기반 원격 서비스 → OAuth. MCP 서버가 401 Unauthorized를 돌려주어 인증이 필요하다고 알리면, 클라이언트가 브라우저 로그인 흐름을 시작합니다. 사용자가 접근을 승인하면 토큰이 발급되어 저장되고, 사람이 손으로 시크릿을 복사하는 과정이 없습니다. 클라우드 서비스·SaaS 도구처럼 사용자의 신원이 권한 판단의 일부인 연동에 맞습니다. 이 모듈 앞부분의 Linear MCP 서버가 이 방식이고, GitHub 서버는 개인 액세스 토큰을 헤더로 전달합니다.
• 서비스 계정 기반 원격 서비스 → 환경 변수의 API 키. 이 키가 서비스 계정을 식별합니다. 키는 설정 파일에 커밋하지 않고, 실행 시점의 환경에 둡니다. Agent SDK를 쓰는 CI 파이프라인이라면 파이프라인 러너가 키를 시크릿으로 주입하고, 코드에는 넣지 않습니다.
• 로컬 파일 시스템 접근 서비스 → 파일 시스템 권한. 네트워크 인증이 없는 stdio(표준 입출력) 전송을 씁니다. 보안 경계는 파일 시스템 권한 모델이고, 설정 파일의 거부 규칙이 통제 계층 역할을 합니다.

인증 방식을 고르면 연결은 만들어집니다. 그런데 그 연결을 안전하게 유지하는 것은 별개의 문제입니다. 앞에서 이야기한 MCP 키 유출은 인증 방식을 잘못 골라서가 아니라, 자격 증명이 있으면 안 되는 자리에 놓여 한 번 퍼진 뒤로는 되돌릴 수 없었기 때문에 생긴 일입니다. 이런 일을 막는 방법은 세 가지이고, 각각 자격 증명이 노출되는 서로 다른 경로에 대응합니다.

분리(separation) — 자격 증명은 그것을 참조하는 설정과 같은 곳에 두지 않습니다. 설정 파일에는 변수 이름표만 두고, 실제 값은 파일이 닿지 않는 곳에 둡니다. 유출 사고가 어긴 규칙이 바로 이것입니다. 이유는 기계적입니다. 설정 파일은 커밋되고, 공유되고, 복제됩니다. 값을 파일 안에 직접 적어 두면 그 복사본마다 값이 함께 따라가고, 한 번 커밋된 값은 나중에 덮어써도 저장소 기록에서 사라지지 않습니다. 값을 파일 밖에 두면, 그 파일은 공유해도 안전합니다.

값을 어디에 두는가 — 값이 파일 밖으로 나온 다음의 문제입니다. 한 대의 컴퓨터나 한 번의 파이프라인 실행에서만 쓰는 값이라면, 실행 시점에 주입하는 환경 변수로 충분합니다. CI 러너가 값을 시크릿으로 설정하고, 설정 파일은 이름으로 그 값을 읽고, 디스크에는 아무것도 적히지 않습니다. 여러 서비스나 사람이 함께 쓰는 값이라면 시크릿 저장소가 낫습니다. 시크릿 저장소는 자격 증명을 모아 두고, 권한 있는 호출자에게 실행 시점에 돌려주며, 누가 무엇을 읽었는지 기록하는 관리형 서비스입니다. 값을 한곳에 모아 두므로 한 번의 교체로 모든 사용처가 함께 갱신되고, 서비스마다 자기 파일에 자격 증명을 따로 두면서 쌓이던 복사본도 사라집니다. 값이 로컬에 있고 수명이 짧으면 환경 변수를, 여러 곳이 함께 쓰거나 감사가 필요하면 시크릿 저장소를 고르면 됩니다.

교체(rotation) — 자격 증명을 주기적으로, 그리고 노출이 의심되면 즉시 새 값으로 바꾸는 일입니다. 유출된 키에 맞는 대응은 교체뿐입니다. 한 번 노출된 키는 다시 비밀로 되돌릴 수 없으니, 새로 발급하는 수밖에 없습니다. 자격 증명을 코드에 직접 적어 넣는 방식이 비싼 이유가 여기 있습니다. 커밋된 코드 안의 값은 깨끗하게 교체하기 어렵습니다. 옛 값이 기록에 남고, 그 값에 맞춰 적어 둔 사용처는 값이 바뀌는 순간 전부 깨집니다. 반면 시크릿 저장소나 환경 변수에서 읽는 자격 증명은 그것을 쓰는 코드를 건드리지 않고도 교체됩니다. 코드는 값을 이름으로 참조하고, 뒤에 있는 값이 바뀌어도 이름은 그대로이기 때문입니다.

교체를 더 수월하게 만드는 두 가지 습관이 있습니다.

• 각 자격 증명의 접근 범위를 필요한 만큼만 좁힙니다. 그러면 키가 유출돼도 그 연동이 필요로 했던 범위까지만 닿습니다.
• 어떤 서비스가 각 자격 증명을 쓰는지 기록해 둡니다. 그래야 교체할 때 사용처를 뒤늦게 찾아 헤매지 않습니다.

정리하면, 앞선 유출 사고가 드러낸 실수는 커밋되는 파일에 자격 증명을 직접 적어 넣은 것이었습니다. 분리는 값을 파일 밖으로 빼내고, 시크릿 저장소나 환경 변수는 파일이 공유하지 않는 자리를 값에 내어 주며, 교체는 앞의 두 가지가 지켜질 때에만 복구 수단이 됩니다.

금융이나 의료처럼 규제를 받는 고객은 '인증이 되는가' 하나만 묻지 않습니다. 데이터가 어디서 처리되는지, 접근이 어떻게 기록되는지, 그리고 감사 기간에 개발자가 인증 설정을 바꾸지 못하도록 관리자가 설정을 잠글 수 있는지를 함께 묻습니다. 이 모듈이 앞에서 다룬 도구들이 세 물음에 각각 답을 줍니다.

• 엔터프라이즈 관리 설정은 마지막 물음(설정 잠금)에 답합니다. 관리자가 배포한 서버 설정을 개별 사용자가 덮어쓸 수 없으면, 인증 설정이 조직 전체에서 일관되게 유지되고, 각 개발자의 설정 파일이 맞는지에 기대지 않아도 됩니다.
• 감사 훅은 기록에 대한 물음에 답합니다. 모든 도구 호출과 그 인자를 감사 로그에 남기는 PostToolUse 훅은 규제 검토가 요구하는 기록을 제공합니다. 이 훅은 모델의 판단과 무관하게 호출마다 실행되고, 모델이 건너뛸 수 있는 기록이 아닙니다.
• 데이터 레지던시는 처리 위치에 대한 물음에 답합니다. 특정 지역의 HTTP 엔드포인트로 설정한 서버와, 처리를 그 지역으로 고정하는 플랫폼 배포를 함께 쓰면, 데이터가 어디로 가는지 검토자가 확인할 수 있는 답이 됩니다.

앞 섹션에서 다룬 인프라 요건과 플랫폼 선택이 빌드할 때만이 아니라 감사할 때 중요해지는 이유가 여기 있습니다.

레거시 코드 현대화는 이 모듈이 다룬 도구 전체를 시험해 보기에 좋은 사례입니다. 각 도구가 관리하도록 설계된 위험이 한곳에 모여 있기 때문입니다. 익숙하지 않은 레거시 코드베이스를 크게 바꾸는 일에는 넓은 파급 범위, 예측하기 어려운 의존 관계, 제한적인 되돌리기라는 위험이 따릅니다. 이 위험들은 작업을 시작하기 전에 모듈의 도구를 적용해 두면 하나씩 줄여 갈 수 있습니다.

핵심 작업 흐름은 탐색·계획·구현 루프(explore, plan, code)입니다. 플랜 모드는 에이전트를 읽기 전용 탐색 단계에 붙들어 두어, 변경 내용에 확신이 설 때까지 기다리게 합니다. 제안된 수정을 미리 검토하고, 예상하지 못한 경로를 건드리는 부분을 찾아내고, 파일이 하나라도 바뀌기 전에 되짚어 볼 수 있습니다. 훅은 가장 민감한 단계에서 특정 경로의 수정을 막는 가드레일을 강제합니다. CLAUDE.md에는 새로 적용할 목표 패턴의 규칙을 적어 두어, 에이전트가 주변 코드의 레거시 패턴으로 되돌아가지 않고 전체 범위에 일관되게 적용하게 합니다.

위험이 높은 작업이라면, 세션을 시작하기 전에 세 가지 물음을 미리 정리해 두는 것이 좋습니다.

• 파급 범위는 어디까지인가. 바꾸려는 코드에 어떤 시스템이 의존하고 있고, 수정이 잘못되면 그 뒤에서 무엇이 깨지는가?
• 변경은 어떻게 기록으로 남기는가. 모든 도구 호출을 남기는 PostToolUse 훅이 있는가, 그 기록이 검토자가 확인해야 할 것을 만족시키는가?
• 각 단계는 누가 승인하는가. 플랜 모드가 탐색과 실행 사이의 경계를 지켜 주지만, 승인 결정 자체는 작업을 시작하기 전에 직접 정하고 적어 두는 몫입니다.

이 물음들은 현대화 작업에만 해당하는 것이 아닙니다. 위험이 높은 에이전트 작업이라면 어디에나 적용됩니다. 다만 현대화는 범위가 넓고, 코드베이스가 낯설고, 틀렸을 때의 비용이 크기 때문에 이 물음들이 더 또렷하게 드러납니다.

아래 표는 서비스 유형별로 정해야 할 핵심 결정을 한눈에 모은 것입니다. 인증 방식·시크릿 위치·남기는 기록·설정 잠금 권한, 이 네 가지가 유형마다 어떻게 달라지는지 비교해 보세요.

SERVICE TYPE → KEY DECISIONS — 유형별 핵심 결정

COST · COMPLEXITY · RISK — 세 가지 관점

• 비용. OAuth 흐름은 서비스마다·사용자마다 한 번씩 초기 설정 단계가 듭니다. API 키 방식은 시크릿 교체 절차가 필요하고, PostToolUse 훅으로 감사 로그를 남기면 도구 호출마다 약간의 부담이 더해집니다.
• 복잡성. 규제 환경은 프로토타입에는 없던 요건을 더합니다. 그 요건을 범위 산정(스코핑) 단계에서 미리 찾아내는 것이, 연동을 일정 안에 지키는 방법입니다.
• 위험. 위험은 프로토타입이 프로덕션으로 넘어갈 때 몰립니다. 자격 증명을 코드에 직접 적어 두고, 감사 로그가 없고, 중앙에서 잠글 수 없는 시스템은 규제 고객의 보안 검토를 통과하지 못합니다. 고치는 일 자체는 어렵지 않지만, 검토 전에 미리 챙겨 둬야 합니다.

WHEN IT FITS — 이 체크리스트가 필요한 때

스테이징에서는 OAuth 연결이 처음부터 끝까지 잘 됐습니다. 그래서 프로덕션으로 옮기는 일도 늘 하던 이전 작업처럼 느껴졌습니다. 팀이 놓친 것은 OAuth 리다이렉트 URIOAuth 로그인을 마친 뒤 사용자를 되돌려 보낼 주소. OAuth 제공자는 미리 등록해 둔 것만 허용한다.가 호스트별로 등록되고 환경마다 따로 통제되는 경우가 많다는 점입니다. 스테이징에서 성공했다고 해서, 프로덕션 호스트가 로그인 흐름을 완료할 권한을 얻은 것은 아니었습니다.

아래는 프로덕션에서 MCP 연동이 실패한 뒤 열린 배포 후 점검 자리에서 오간 대화입니다. 이 연동은 스테이징 테스트를 모두 통과한 상태였습니다.

개발자는 스테이징에서 OAuth 흐름을 처음부터 끝까지 시험해 동작을 확인했으니, 프로덕션 실패는 코드 결함이 아니었습니다. 호스트마다·환경마다 따로 해 줘야 하는 설정 단계였는데, 프로덕션에서도 그 단계가 필요하다는 것을 몰랐던 것입니다.

아래 연결 로그를 읽고, 어떤 인증 실패가 일어났는지 짚어 본 다음, 세 가지 조치 중 알맞은 것을 골라 보세요. 정답을 먼저 떠올려 본 뒤 골라 보면 좋습니다. 맞히면 설명이 나옵니다.

CONNECTION TRACE — CI 러너의 MCP 연결 로그

[MCP Client] Connecting to https://data-api.internal/mcp …
[MCP Client] GET /auth/token, 401 Unauthorized
[MCP Client] Reading credential from: /home/jenkins/.config/mcp-credentials.json
[MCP Client] Credential value: WAREHOUSE_TOKEN= sk-****[redacted]
[MCP Client] Retrying with credential, 401 Unauthorized
[MCP Client] Connection failed after 3 attempts

이어서 본문 내용을 두 문항으로 더 점검합니다.