Quick Reference
custom connector는 Claude 계정에 remote MCP server를 연결하는 방식입니다. 서버 연결은 사용자의 노트북이 아니라 Anthropic cloud에서 시작하므로, private VPN·사내망에서만 열리는 주소에는 맞지 않습니다. 외부 업무 도구를 읽거나 변경해야 할 때만 쓰고, 로컬 파일·로컬 프로세스 접근이 목적이면 Claude Desktop 또는 Claude Code의 local MCP와 구분합니다.
| 필요한 일 | 먼저 고를 방식 | 확인할 경계 |
|---|---|---|
| 공식 서비스 연동 | pre-built connector | 제공자·조직이 검토한 연결인지 확인합니다. |
| 자체 SaaS·공개 API 연동 | remote MCP custom connector | Anthropic cloud에서 public endpoint까지 닿아야 합니다. |
| 로컬 파일·개발 도구 접근 | local MCP 또는 Claude Code | 사용자 장비에서 실행되는 server와 권한을 따로 관리합니다. |
| 읽기 전용 분석 | read tool만 제공하는 server | OAuth scope와 tool 입력·출력을 좁힙니다. |
| 생성·수정·삭제 | 명시적인 write tool | 대상·되돌리기·감사 기록을 먼저 정합니다. |
연결 전
server 출처와 URL -> OAuth scope -> tool별 read/write 성격 -> 데이터가 나가는 위치
연결 후
실제 계정 -> 노출된 tool 목록 -> 작은 읽기 요청 -> write action 승인 범위실행 위치와 연결 조건
remote MCP custom connector는 Claude, Cowork, Claude Desktop 등에서 쓸 수 있어도 연결 요청 자체는 Anthropic의 cloud infrastructure에서 server로 향합니다. Desktop이 로컬 컴퓨터에서 실행된다는 사실은 이 경로를 바꾸지 않습니다. 따라서 사용자의 VPN에서만 접근되는 주소, private corporate network, inbound firewall로 막힌 endpoint는 사용자의 브라우저에서 열려도 connector가 연결하지 못합니다.
private network의 server를 써야 한다면 공개 노출을 서두르기보다 네트워크 정책을 검토합니다. 도움말이 안내하는 Anthropic IP range allowlist, endpoint 인증, 필요한 ingress 범위를 보안 담당자와 함께 정합니다. local MCP server는 별도 메커니즘이며 custom connector의 대체가 아니라 실행 위치가 다른 선택지입니다.
| 연결 방식 | server가 실행되는 곳 | Claude가 닿는 경로 | 주로 생기는 실패 |
|---|---|---|---|
| remote custom connector | 인터넷에 공개된 server | Anthropic cloud -> remote endpoint | VPN 전용 주소, firewall, OAuth redirect 불일치 |
| local MCP | 사용자 장비의 process | local Claude client -> local process | PATH·환경 변수·프로세스 권한·로컬 secret |
| Claude Code remote MCP | HTTP endpoint 또는 stdio process | 설정한 transport와 scope | 중복 정의, token·scope 누락, project approval |
권한과 tool 설계
connector URL을 추가하는 일은 단순 링크 등록이 아닙니다. server가 제공하는 tool은 Claude가 외부 시스템에서 읽기·생성·수정·삭제할 수 있는 API 표면입니다. custom connector는 Anthropic이 검증하지 않은 service일 수 있으므로, server 운영 주체와 source code 또는 배포 이력, OAuth authorization page의 scope, tool 이름과 실제 side effect를 함께 확인합니다.
읽기 tool: 검색·조회·미리보기처럼 상태를 바꾸지 않는가?
쓰기 tool: 생성·수정·삭제 대상이 명시적인가? rollback 또는 audit log가 있는가?
데이터: prompt와 tool output에 고객 정보·secret이 섞이지 않는가?
인증: 개인 계정 권한인가, 팀용 service account 권한인가?Team·Enterprise에서는 connector를 조직에 추가하는 역할과 각 사용자가 연결·인증하는 역할이 분리될 수 있습니다. "팀에서 connector를 추가했다"는 사실만으로 모든 사용자가 인증을 마쳤거나 같은 데이터 권한을 가진다는 뜻은 아닙니다. 민감한 tool은 최소 OAuth scope, 대상 리소스 allowlist, server 측 authorization과 audit log로 제한합니다.
Claude의 prompt 지시는 외부 system의 인가를 대신하지 않습니다. read-only라고 설명한 tool도 server token이 쓰기 권한을 갖고 있으면 side effect를 만들 수 있으므로, 실제 권한은 OAuth scope와 server API 정책에서 막아야 합니다.
연결이 안 되거나 위험해 보일 때
| 증상 | 먼저 확인할 것 | 대응 |
|---|---|---|
| Desktop에서는 되는데 custom connector가 연결되지 않음 | endpoint가 public internet에서 도달 가능한지 | private network라면 allowlist·gateway 또는 local MCP를 검토합니다. |
| 인증은 끝났는데 필요한 데이터가 없음 | OAuth scope·조직 권한·리소스 공유 범위 | 사용 계정과 scope를 다시 확인하고 broad admin token을 쓰지 않습니다. |
| tool 설명이 모호하거나 의도보다 큰 결과를 냄 | server 출처·schema·write effect | 연결을 끊고 검증된 server·read-only 계정으로 교체합니다. |
| 같은 server를 Claude Code에서도 설정함 | endpoint 중복과 활성 인증 방식 | /mcp, claude mcp list, connector 상태를 확인하고 한 정의를 기준으로 둡니다. |
참고 링크
2 sources