모델 컨텍스트 프로토콜(MCP) 통합

적절한 액세스 권한이 있는 MCP 서버 엔드포인트입니다.

필요한 경우 MCP 서버의 인증 자격 증명입니다. 자세한 내용은 MCP 서버 설정 및 인증 준비 단원을 참조하십시오.

Amazon Quick Enterprise 구독.

프라이빗 MCP 서버에 연결하는 경우 MCP 서버에 대한 네트워크 액세스 권한이 있는 활성 Amazon Quick VPC 연결입니다. 자세한 내용은 Amazon Quick Sight에서 VPC 연결 구성 단원을 참조하십시오.

커넥터는 검색을 통과하지만에 게시할 때 실패Creation failed합니다.이 오류는 일반적으로 MCP 서버의 tools/list 응답에 있는 하나 이상의 도구 정의에 잘못된가 포함되어 있음을 의미합니다inputSchema. Amazon Quick은 게시 단계에서 JSON 스키마 초안 7 이상을 inputSchema 기준으로 각 도구의 유효성을 검사합니다.

가장 일반적인 원인은 사용되지 않는 초안 3 구문입니다. 여기서 required는 속성 정의(예: ) 내의 부울입니다"required": true. JSON 스키마 초안 7 이상에서는가의 형제로서 스키마 루트의 속성 이름 배열이어야 required 합니다properties.

올바른 형식을 사용하도록 도구 정의를 업데이트하고 MCP 서버를 재배포합니다. 재배포한 후 실패한 커넥터를 삭제하고 검색을 다시 트리거하고 게시할 새 커넥터를 생성합니다.

다음 예제에서는 잘못된 초안 3 구문을 보여줍니다.

{
  "type": "object",
  "properties": {
    "logNumber": {
      "type": "string",
      "description": "The permit log number",
      "required": true
    }
  }
}

다음 예제에서는 올바른 초안 7 구문을 보여줍니다.

{
  "type": "object",
  "properties": {
    "logNumber": {
      "type": "string",
      "description": "The permit log number"
    }
  },
  "required": ["logNumber"]
}

일부 MCP 프레임워크 라이브러리 및 코드 생성기는 기본적으로 초안 3 구문을 내보냅니다. 프레임워크 설명서에서 JSON 스키마 출력 버전을 선택하는 옵션을 확인합니다. 배포하기 전에 모든 JSON 스키마 초안 7 검사기를 사용하여 스키마를 검증할 수도 있습니다. inputSchema 요구 사항에 대한 자세한 내용은 모델 컨텍스트 프로토콜 사양의 도구를 참조하세요.

커넥터 생성이 실패하기 전에 2~5분 동안 중단될 수도 있습니다. 경과 시간은 네트워크 제한 시간이 아닌 게시 단계 동안의 내부 재시도를 반영합니다. 수정 사항은 동일합니다. 도구 inputSchema 정의에서 JSON 스키마 초안 7 규정 준수를 확인합니다.

VPC 연결이 연결 유형 드롭다운에 나열되지 않거나 선택한 직후 MCP 생성이 실패함 - 프로비저닝이 완료되기 전에 VPC 연결이 드롭다운에 표시될 수 있습니다. VPC 연결이 Amazon Quick Admin 페이지에 사용 가능한 것으로 표시될 때까지 기다렸다가 이에 대한 MCP 통합을 생성합니다. 자세한 내용은 Amazon Quick Sight에서 VPC 연결 구성 단원을 참조하십시오.

MCP 서버 호스트 이름을 확인할 수 없으므로 MCP 생성이 실패합니다. Amazon Quick은 MCP 통합에 기본 VPC DNS 해석기를 사용하지 않습니다. VPC 연결의 DNS 해석기 엔드포인트 필드를 MCP 서버 호스트 이름을 확인할 수 있는 Route 53 Resolver 인바운드 엔드포인트 IP 주소로 채워야 합니다. 이 요구 사항은 프라이빗 호스트 이름과 VPC 내에서 프라이빗 주소로 확인하려는 퍼블릭 호스트 이름 모두에 적용됩니다. 예를 들어 AWS , PrivateLink 또는 Route 53 프라이빗 호스팅 영역이 앞에 있는 엔드포인트가 여기에 해당합니다. 이러한 해석기 엔드포인트가 없으면 MCP 서버 호스트 이름을 확인할 수 없으며 통합 생성이 실패합니다. 자세한 내용은 Amazon Quick Sight에서 VPC 연결 구성 단원을 참조하십시오.

VPC 연결에서 MCP 서버에 연결할 수 없음 - Amazon Quick에서 MCP 서버로의 트래픽은 VPC 연결 설정 중에 선택한 서브넷에서 비롯됩니다. 라우팅 테이블, 네트워크 ACLs 및 보안 그룹이 해당 서브넷과 MCP 서버 엔드포인트 간의 트래픽을 허용하는지 확인합니다. 일반적인 VPC 네트워킹 지침은 섹션을 참조하세요Amazon Quick Sight에서 VPC 연결 구성.

프라이빗 MCP 서버를 사용할 때 인증 실패 - VPC 연결을 통해 프라이빗 MCP 서버에 연결할 때 MCP 서버에서 사용하는 OAuth 엔드포인트는 여전히 퍼블릭 인터넷을 통해 연결할 수 있어야 합니다. 이는 사용자 인증(권한 부여 및 토큰 엔드포인트)과 서비스 인증(토큰 엔드포인트) 모두에 적용됩니다. 프라이빗 OAuth 공급자는 지원되지 않습니다. MCP 서버가 보호된 리소스 메타데이터에서 반환하는 OAuth URLs이 퍼블릭 인터넷을 통해 확인되는지 확인합니다.

AADSTS9010010 - v2.0 엔드포인트가 리소스 파라미터를 거부함 - Amazon Quick은 MCP 사양(RFC 8707)에 따라 OAuth 요청에 resource 파라미터를 보냅니다. Entra ID v2.0 엔드포인트는 resource 파라미터와 scope 값을 모두 포함하는 요청을 거부합니다. 이 오류를 해결하려면 Entra ID v1.0 OAuth 엔드포인트를 사용하도록 앱 등록을 구성하고 앱 매니페스트2에서를 accessTokenAcceptedVersion로 설정합니다.

AADSTS90009 - 애플리케이션이 토큰 자체 요청 - 사용자 인증(권한 부여 코드 흐름)을 사용하고 OAuth 클라이언트와 MCP 리소스가 동일한 Entra ID 애플리케이션으로 확인되면 Entra ID가 요청을 차단합니다. Amazon Quick용 클라이언트 앱 하나와 MCP 서버용 리소스 앱 하나라는 두 개의 개별 앱 등록을 생성합니다. 이 문제는 단일 앱 등록이 작동하는 서비스 인증(클라이언트 자격 증명 흐름)에는 영향을 주지 않습니다.

MCP 작업의 제한 시간은 60초로 고정되어 있습니다. 이 제한을 초과하는 작업은 HTTP 424 오류와 함께 자동으로 실패합니다.

VPC 연결을 통해 도달하는 MCP 서버의 경우 MCP 서버에서 사용하는 OAuth 엔드포인트는 퍼블릭 인터넷을 통해 연결할 수 있어야 합니다. 이는 사용자 인증과 서비스 인증 모두에 적용됩니다. 프라이빗 OAuth 공급자는 지원되지 않습니다.

사용자 지정 HTTP 헤더는 MCP 작업에서 지원되지 않습니다. 표준 시스템 헤더만 전송됩니다.

도구 목록은 초기 등록 후에도 정적 상태를 유지합니다. 서버 측 도구 변경 사항을 선택하려면 통합을 삭제하고 다시 생성해야 합니다.

Amazon Quick 콜백 URI가 타사 공급자에 의해 허용 목록에 없는 경우 커넥터 생성이 실패할 수 있습니다.

서버 연결 문제로 인해 재시도 없이 즉시 실패합니다.

단계적 권한 부여는 지원되지 않습니다. MCP 서버에 초기 권한 부여(를 사용한 HTTP 403insufficient_scope) 후 추가 범위가 필요한 경우 전체 연결을 다시 권한 부여해야 합니다. 증분 권한 업그레이드는 사용할 수 없습니다.

범위 처리에는 다음과 같은 제한 사항이 있습니다.

자동 클라이언트 등록에는 동적 클라이언트 등록(DCR)만 지원됩니다. 클라이언트 ID 메타데이터 문서는 지원되지 않습니다.

잘 알려진 URI 검색은 서버 루트 경로만 사용합니다. 경로별 메타데이터 위치(경로 삽입 검색)는 지원되지 않습니다. 이러한 제한으로 인해 경로별 URIs.