로컬 MCP 서버 문제 해결

인증 요구 사항

필수: Atlas API 자격 증명
• apiClientId (서비스 계정 ID)
• apiClientSecret (서비스 계정 비밀)

필수 사항: Docker 런타임
• 별도의 자격 증명이 필요 없습니다
• 로컬 배포서버를 자동으로 관리합니다

선택 사항: 다중 연결 방법
• 사전 구성된 연결 문자열
• atlas-connect-cluster의 Atlas 자격 증명
• connect 도구를 통한 런타임 연결
• atlas-local-connect-deployment를 통한 로컬 배포서버

연결 메서드

Atlas 관리 API에 대한 API 기반 연결
• 직접적인 데이터베이스 연결 불필요
• Atlas REST API 엔드포인트 사용

로컬 배포서버 관리
• Docker 컨테이너 사용
• 외부 네트워크 액세스 필요 없음

MongoDB 데이터베이스에 직접 연결. 사용 가능한 옵션이 여러 개 있습니다.
• 구성된 연결 문자열
• 런타임 연결 프롬프트
• Atlas 클러스터 발견
• 로컬 배포서버 연결

권한 요구 사항

서비스 계정 역할 (Atlas 프로젝트 수준):
• Project Read Only (읽기 작업의 최소 요건)
• Project Owner (클러스터 생성/관리 용)
• Organization Owner (프로젝트 생성 용)

시스템 요구 사항:
• Docker 런타임 권한
• 로컬 파일 시스템 접근
• 컨테이너 관리 역량

데이터베이스 사용자 역할 (해당되는 경우):
• readAnyDatabase (읽기 전용 모드)
• readWriteAnyDatabase (전체 작업)
• 특정 데이터베이스/컬렉션에 대한 사용자 지정 역할

구성 옵션

환경 변수:
MDB_MCP_API_CLIENT_ID 또는
MDB_MCP_API_CLIENT_SECRET

명령줄:
• --apiClientId
• --apiClientSecret

환경 변수:
• DOCKER_HOST (선택 사항)

명령줄:
• 특별한 MCP 구성이 필요하지 않음
• Docker 런타임 자동 감지

환경 변수 (선택 사항):
MDB_MCP_CONNECTION_STRING

명령줄 (선택 사항):
• 위치 인수로서의 연결 문자열:
--connectionString

런타임 메서드:
• LLM 프롬프트를 통한 상호 작용 연결
• Atlas 자격 증명 기반 발견

읽기 전용 모드 영향

• 읽기 작업: ✅ 사용 가능
• 클러스터 검사: ✅ 사용 가능
• 클러스터 생성: ❌ 비활성화됨
• 사용자 관리: ❌ 비활성화됨

• 로컬 배포서버 생성: ✅ 사용 가능
• 배포서버 검사: ✅ 사용 가능
• 컨테이너 관리: ✅ 사용 가능
• 읽기 전용 제한 없음

• 읽기 작업: ✅ 사용 가능
• 쿼리 작업: ✅ 사용 가능
• 집계: $out 또는 $merge 단계가 없는 한 사용 가능
• 삽입/업데이트/삭제: ❌ 비활성화
• 인덱스 생성: ❌ 비활성화

도구 카테고리

다음을 사용하여 비활성화할 수 있습니다:
--disabledTools atlas 또는
MDB_MCP_DISABLED_TOOLS="atlas"

다음을 사용하여 비활성화할 수 있습니다:
--disabledTools atlas 또는
MDB_MCP_DISABLED_TOOLS="atlas"

다음을 사용하여 비활성화할 수 있습니다:
--disabledTools mongodb 또는
MDB_MCP_DISABLED_TOOLS="mongodb"

네트워크 요구 사항

Atlas API로의 출력 HTTPS 연결:
• 표준 인터넷 연결

로컬 Docker 네트워크:
• Docker 데몬 액세스
• 로컬 포트 사용 가능
• 외부 네트워크 요구 없음

MongoDB 클러스터에 연결 (해당하는 경우):
• Atlas: mongodb+srv:// (포트 27017)
• 샤딩된 클러스터 (포트 27016)
• 자체 관리형: 사용자 지정 호스트/포트
• 로컬 배포서버: Docker 네트워크
• 필요한 VPC/네트워크 액세스

사용 가능한 작업

• 조직 관리
• 프로젝트 관리
• 클러스터 라이프사이클(생성, 검사, 삭제)
• 데이터베이스 사용자 관리
• 액세스 목록 구성
• Performance Advisor 권장
• 경고 관리

• 로컬 배포 생성 및 관리
• 컨테이너 수명 주기 작업
• 로컬 클러스터 구성
• 개발 환경 설정
• 테스트 배포 관리

• CRUD 작업(찾기, 삽입, 업데이트, 삭제)
• 집계 파이프라인
• 인덱스 관리
• 컬렉션 및 데이터베이스 관리
• 스키마 검사
• 벡터 검색 작업
• 어휘 검색 작업
• 데이터 내보내기

Error Scenarios

API 자격 증명 누락:
Atlas 도구에서 반환됩니다: "Atlas API 자격 증명이 구성되지 않았습니다."

권한 부족:
Atlas API에서의 HTTP 403 오류

Docker 사용
불가능: "Docker 데모는 실행 중이 아닙니다" 또는 "Docker가 설치되어 있지 않습니다"

컨테이너 문제: 포트
충돌, 리소스 제한

연결 실패 (구성된 경우):
네트워크 타임아웃, 인증 실패

데이터베이스 권한 누락:
MongoDB 권한 부여 오류

임시 자격 증명

해당 없음:
영구 서비스 계정 자격 증명을 사용합니다.

해당 없음:
로컬 배포서버는 컨테이너 managed 인증을 사용합니다.

자동 생성된 데이터베이스 사용자 (해당하는 경우):
연결 문자열 없이 Atlas API 자격 증명을 사용하는 경우:
• 무작위 사용자 이름/비밀번호
• 기본값으로 4시간 만료
• 자동 역할 할당