환경 준비부터
첫 연결까지.

01 / VS Code 확장 설치

VS Code 확장 마켓에서 검색: Claude Code Config Helper, 게시자 확인: liliangshan. 게시 버전은 마켓 페이지 기준이며 로컬 테스트 버전과 다를 수 있습니다.

VSIX로도 설치 가능

로컬 VSIX가 있다면 VS Code의 확장 → … → VSIX에서 설치를 선택하세요. 창을 다시 로드하면 실행 중인 CLI 작업이 중단됩니다.

02 / 3단계 설정 완료

1. 언어 선택 및 CLI 준비안내에서 CLI를 다운로드·검증하거나 기존 실행 파일을 선택하세요. 기본은 공식 소스이며 중국 미러는 직접 선택합니다.
2. 서비스와 모델 추가서비스 주소, 인증 방식, API 키를 설정하고 모델 목록을 가져오거나 직접 추가하세요. 유료 테스트 메시지는 필요 없습니다.
3. 워크스페이스 모델 선택 후 대화기본 모델, 선택적 작업 흐름·압축 모델, 사고 수준을 설정하세요. 오른쪽에 기본 세션이, 병렬 세션을 누르면 왼쪽에 독립 세션이 열립니다.

03 / 도구 선택 및 설정 복사

로컬 설정 예시만 생성하며 서버 연결, 비밀번호 수집, 패키지 설치를 하지 않습니다. 주소와 경로를 바꾸고 인증 정보는 클라이언트에 설정하세요.

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": [
        "-y",
        "@liangshanli/mcp-server-mysql"
      ],
      "env": {
        "MYSQL_HOST": "db.example.com",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "ai_reader",
        "MYSQL_PASSWORD": "${MYSQL_PASSWORD}",
        "MYSQL_DATABASE": "app_db",
        "MYSQL_SSL": "true",
        "READONLY": "true",
        "ALLOW_DDL": "false",
        "ALLOW_DROP": "false",
        "ALLOW_DELETE": "false"
      }
    }
  }
}

MySQL 예시는 읽기 전용과 TLS를 켭니다. 읽기 전용 계정을 사용하고 호스트명과 DB 인증서가 일치하는지 확인하세요.

변수와 설정 형식 차이

• Claude Code：사용: mcpServers, 프로젝트 루트 파일: .mcp.json. 예시 변수 ${MYSQL_PASSWORD} 등은 클라이언트 시작 시 환경 변수에 의존합니다. 실제 클라이언트 규칙을 확인하세요.
• VS Code 기본 MCP:사용: servers, 저장 위치: .vscode/mcp.json. 비밀번호는 웹사이트가 아닌 VS Code 입력 창에서 받습니다.
• Cursor：저장 위치: .cursor/mcp.json, 사용 필드: mcpServers. 환경 변수 확장은 버전에 따라 다릅니다. 미확장 변수를 실제 비밀번호로 사용하지 마세요.
• 이 확장:기본 .mcp.json 는 CLI가 검색하며,--strict-mcp-config 는 소스를 제한합니다. VS Code 설정 읽기는 기본 입력 변수 해석과 다릅니다. 이 확장에서는 Claude Code 형식을 권장합니다.

기존 설정에는 필요한 server 항목만 병합하세요. Windows에서 npx가 안 되면 Node.js 절대 경로와 설치 패키지 진입점을 사용하고 npm 문서를 확인하세요.

04 / 도구 작동 확인

1. 로컬 환경 확인지원되는 Node.js를 설치하세요. SSH는 20+가 필요하며 다른 패키지는 npm을 확인하세요. 클라이언트가 node / npx를 찾을 수 있어야 합니다.
2. MCP 재연결 또는 CLI 재시작설정 저장 후 도구를 다시 로드하세요. 확장에서는 해당 쪽 CLI를 재시작하고 중요한 실행 작업이 없는지 확인하세요.
3. 영향이 적은 작업부터도구 목록과 연결을 먼저 확인한 뒤 DB 구조, Redis 테스트 키, 자체 API GET 요청을 실행하세요.

작업 예시:

현재 MCP 도구의 사용 가능 여부를 확인하세요.
테스트 DB 구조만 읽고 테이블 관계를 설명하세요.
데이터나 구조를 변경하지 말고 연결이나 권한이 없으면 먼저 알려주세요.

05 / 기능보다 범위 먼저

06 / MCP 도구가 안 보이나요?

• 파일명, 폴더, 최상위 필드가 클라이언트와 맞는지 확인하세요.
• JSON, 패키지명, 실행 명령 경로를 확인하세요.
• 워크스페이스 신뢰, MCP 승인, CLI 엄격 모드, 도구 설정을 확인하세요.
• DB / SSH / API 주소, 네트워크, 인증, 서버 권한을 확인하세요.
• 해당 CLI를 재시작하고 로그를 확인하세요. 키가 포함된 설정을 공개 채널에 붙여넣지 마세요.