MCP 구성 - Amazon Q Developer
MCP 구성 이해

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

MCP 구성

Amazon Q Developer CLI의 MCP 구성은 JSON 파일을 통해 관리됩니다. 이 섹션에서는 Q의 기능을 확장하도록 MCP 서버를 구성하는 방법을 다룹니다.

MCP 구성 이해

Amazon Q Developer CLI의 MCP 클라이언트 구성은 라는 파일에 JSON 형식으로 저장됩니다mcp.json. 이 섹션에서는 MCP 구성의 작동 방식과 구성 파일을 구성하는 방법을 설명합니다.

구성 파일 위치

Amazon Q Developer CLI는 두 가지 수준의 MCP 구성을 지원합니다.

  1. 글로벌 구성: ~/.aws/amazonq/mcp.json - 모든 워크스페이스에 적용

  2. 워크스페이스 구성: .amazonq/mcp.json - 현재 워크스페이스에만 해당

두 파일은 모두 선택 사항이며 둘 중 하나 또는 둘 다 존재할 수 없습니다. 두 파일이 모두 있는 경우 Amazon Q Developer CLI는 두 파일 모두에서 MCP 구성을 읽고 결합하여 내용을 결합합니다. 충돌이 있는 경우(즉, 전역 구성에 정의된 서버가 워크스페이스 구성에도 있음) 경고가 표시되고 워크스페이스 구성의 서버 항목만 사용됩니다.

Amazon Q Developer CLI는 이러한 구성 파일을 감시하고 파일을 변경할 때마다 MCP 구성을 자동으로 다시 로드합니다.

구성 파일 구조

MCP 구성 파일은 다음 구조의 JSON 형식을 사용합니다.

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR1": "value1",
        "ENV_VAR2": "value2"
      },
      "timeout": 60000
    }
  }
}

각 MCP 서버 항목은 서버 이름이 키인 객체입니다. 이름은 각 MCP 구성 파일 내에서 전역 및 프로젝트 구성 파일에서 고유해야 합니다. 서버 이름은 비워둘 수 없으며 250자를 초과할 수 없습니다.

각 MCP 서버 항목 객체에는 "명령" 속성(stdio 전송용) 또는 "url" 속성(HTTP 전송용, 향후 릴리스에서 지원됨)이 있어야 합니다.

JSON 파일에 예상치 못한 속성이 있는 경우 경고가 표시되고 해당 속성은 무시됩니다.

Stdio 서버 구성

항목에 "명령" 속성이 있는 경우이 MCP 서버는 stdio 전송을 사용합니다. 다음과 같은 속성이 지원됩니다.

  • command (필수): MCP 서버를 시작하는 데 사용할 셸 명령입니다. 유효한 셸 명령을 나타내는 문자열입니다.

  • args (선택 사항): 시작 시 서버에 전달할 명령줄 인수의 배열입니다. 인수는 구성 파일에 정의된 정확한 순서로 전달됩니다. 정의되지 않은 경우 인수가 서버에 전달되지 않습니다.

  • env (선택 사항): 서버를 시작할 때 설정할 환경 변수가 포함된 객체입니다. 각 값은 문자열이어야 합니다. 정의되지 않은 경우 환경 변수가 설정되지 않습니다.

  • timeout (선택 사항): 클라이언트가 도구 호출, 프롬프트 검색 또는 리소스 검색을 위해 MCP 서버의 응답을 기다리는 최대 밀리초 단위 시간입니다. 이 값은 양의 정수 값이어야 합니다. 정의되지 않은 경우 기본값인 60,000ms(1분)가 사용됩니다.

환경 변수 대체:

  • ${env:VAR_NAME}: 환경 변수 VAR_NAME의 값을 대체합니다.

  • ${file:/path/to/file}: 지정된 파일의 내용을 대체합니다.

stdio 서버 구성의 예:

{
  "mcpServers": {
    "stdio-mcp-server": {
      "command": "mycommand",
      "args": [
        "arg1"
      ],
      "env": {
        "API_KEY": "value1"
      },
      "timeout": 60000
    }
  }
}

구성 예제

단일 MCP 서버가 있는 기본 예제:

{
  "mcpServers": {
    "markdown-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@example/markdown-mcp"
      ]
    }
  }
}

여러 MCP 서버 및 환경 변수가 있는 예제:

{
  "mcpServers": {
    "git-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@example/git-mcp"
      ],
      "timeout": 30000
    },
    "api-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@example/api-mcp"
      ],
      "env": {
        "API_URL": "https://api.example.com",
        "API_KEY": "your-api-key"
      },
      "timeout": 120000
    }
  }
}

구성 모범 사례

  • MCP 서버의 이름을 설명하여 쉽게 식별할 수 있도록 합니다.

  • API 키와 같은 민감한 정보는 구성 파일에 하드 코딩하는 대신 환경 변수로 저장합니다.

  • 모든 프로젝트에서 사용하려는 MCP 서버의 글로벌 구성 파일을 사용합니다.

  • 특정 프로젝트와만 관련된 MCP 서버에 워크스페이스별 구성 파일을 사용합니다.

  • 각 MCP 서버의 예상 응답 시간을 기반으로 제한 시간 값을 조정합니다.

  • MCP 서버에 대한 업데이트를 정기적으로 확인하여 최신 기능과 보안 수정 사항이 있는지 확인합니다.

구성 명령

사용량: Usage: qchat mcp [OPTIONS] COMMAND

MCP 구성 명령
Command 설명
qchat mcp add 구성된 서버 추가 또는 교체
qchat mcp remove MCP 구성에서 서버 제거
qchat mcp list 구성된 서버 나열
qchat mcp import 다른 파일에서 서버 구성 가져오기
qchat mcp status 구성된 서버의 상태 가져오기
qchat mcp help 지정된 하위 명령(들)에 대한 명령 또는 도움말 목록을 인쇄합니다.