등록 문제 해결하기

연결된 앱을 등록하거나 구성하는 중에 문제가 발생하면 다음 표에서 일반적인 오류 메시지, 원인, 문제 해결 단계를 참고하세요.

문제	오류 메시지	원인	해결/문제 해결 단계
지정되지 않은 '도구 가져오기' 실패	'MCP 서버 세부정보를 가져올 수 없습니다. 다시 시도해 주세요.' (또는 도구 가져오기 버튼이 특정 오류 메시지 없이 실패함)	잘못된 URL, 오프라인 서버 또는 네트워크 오류로 인해 Connected Console에서 MCP 엔드포인트에 대한 요청을 완료할 수 없습니다.	다음을 확인합니다. MCP 엔드포인트 URL이 정확하고 https://를 사용하는지 다시 한번 확인하세요. MCP 서버가 실행 중인지 확인합니다. 공개 인터넷에서 MCP 서버에 액세스할 수 있는지 확인합니다(Google은 localhost 또는 비공개 인트라넷 주소에 연결할 수 없음).
MCP 서버에 연결할 수 없음	'MCP 서버에 연결할 수 없습니다'	Google 백엔드에서 MCP 엔드포인트에 연결할 수 없습니다.	일반적인 원인과 해결 방법은 다음과 같습니다. 방화벽 제한: 방화벽 또는 WAF가 Google의 아웃바운드 IP 범위를 차단하지 않는지 확인합니다. API Gateway 규칙: API Gateway가 POST 요청을 수락하고 MCP initialize 핸드셰이크 중에 Google의 clientInfo를 거부하지 않는지 확인합니다. 하위 도메인 불일치: 전용 하위 도메인(예: gemini.mcp.company.com)을 사용하는 경우 /.well-known/oauth-protected-resource 메타데이터가 다른 기본 도메인(mcp.company.com)을 가리키지 않고 해당 하위 도메인과 일치하는지 확인합니다.
지원되지 않는 MCP 전송(HTTP 405)	'MCP 서버에서 요청을 거부했습니다(HTTP 405 메서드 허용되지 않음). URL이 기존 SSE 엔드포인트가 아닌 POST 요청을 허용하는 스트리밍 가능한 HTTP 엔드포인트를 가리키는지 확인하세요."	엔드포인트 URL이 GET 요청만 허용하거나 JSON-RPC POST 요청을 거부하는 기존 HTTP+SSE 엔드포인트를 가리킵니다.	initialize 및 tools/list에 대한 POST 요청을 허용하는 MCP 스트리밍 가능한 HTTP 전송을 사용하도록 MCP 서버 및 엔드포인트 URL을 업데이트합니다.
OAuth 보호 리소스 파일 누락	'MCP 서버에 /.well-known/oauth-protected-resource 파일이 없습니다'	Google에서 OAuth 2.0 보호 리소스 메타데이터 검색(RFC 9728)을 시도했으나 실패했습니다.	MCP 서버에 인증이 필요하지 않은 경우: 이 오류는 일반적으로 MCP 엔드포인트 URL에 오타가 있거나 경로 세그먼트가 누락되어(예: https://mcp.example.com/mcp 대신 https://mcp.example.com) HTTP 404 또는 500를 반환하여 클라이언트가 OAuth 검색으로 대체될 때 발생합니다. 정확한 MCP 엔드포인트 경로가 인증되지 않은 POST initialize 및 tools/list 요청에 대해 HTTP 200 OK를 반환하는지 확인하고 액세스 사용자 인증 정보의 서버에 승인이 필요한가요?에서 아니요를 선택합니다. MCP 서버에 인증이 필요한 경우: authorization_servers 배열에서 신뢰할 수 있는 승인 서버를 알리는 유효한 /.well-known/oauth-protected-resource JSON 파일을 MCP 서버에서 호스팅합니다.
OAuth 승인 서버 메타데이터가 누락되었거나 잘못됨	'/.well-known/oauth-authorization-server 파일이 OAuth 서버에 없습니다' 또는 '잘못되었거나 불완전한 JSON이 포함되어 있습니다'	OAuth 서버가 /.well-known/oauth-authorization-server에서 유효한 RFC 8414 메타데이터 문서를 노출하지 않습니다.	authorization_endpoint 및 token_endpoint가 포함된 유효한 RFC 8414 탐색 문서를 /.well-known/oauth-authorization-server(또는 /.well-known/openid-configuration)에서 호스팅합니다. 또는 사용자 인증 정보 섹션에서 커스텀 승인 엔드포인트 및 커스텀 토큰 엔드포인트 URL을 수동으로 입력합니다.
도메인 확인 실패	도메인 인증서에 '확인 실패' 또는 '인증 실패'가 도움말 메시지(예: HTTP 404, 리디렉션 허용되지 않음 또는 토큰 불일치)와 함께 표시됩니다.	Google에서 https://<domain>/.well-known/google-connected-apps의 챌린지 토큰을 확인할 수 없습니다.	파일을 찾을 수 없음(HTTP 404): 다운로드한 google-connected-apps.json 콘텐츠가 https://<domain>/.well-known/google-connected-apps에 게시되었는지 확인합니다(URL 경로에 .json 확장자 없음). 리디렉션 허용되지 않음: HTTP 200 OK를 사용하여 인증 페이로드를 직접 제공합니다. /.well-known/google-connected-apps를 다른 URL로 리디렉션하지 마세요. 토큰 불일치: JSON 응답에 개발자 계정에 생성된 정확한 토큰이 포함된 "verification_tokens": ["<YOUR_TOKEN>"]가 있는지 확인합니다.
동적 클라이언트 등록(DCR) 또는 CIMD 실패	'동적 클라이언트 등록(RFC 7591)에 실패했습니다', 'OAuth 서버가 동적 클라이언트 등록(RFC 7591)을 지원하지 않습니다' 또는 '클라이언트 ID 메타데이터 문서(CIMD) 등록에 실패했습니다'	자동 OAuth 클라이언트 등록에 실패했거나 OAuth 제공업체에서 지원하지 않거나 Google의 리디렉션 URI가 거부되었습니다.	OAuth 서버가 서버 인증 사용자 인증 정보(https://oauth-redirect.googleusercontent.com/r/<app-id>-<sanitized-domain> 등)에 표시된 6개의 앱별 Google 리디렉션 URI를 모두 허용 목록에 추가하는지 확인합니다. 많은 OAuth 2.1 서버는 와일드 카드(*) 리디렉션 URI를 거부합니다. OAuth 제공업체에서 CIMD 또는 RFC 7591 DCR을 지원하지 않는 경우 액세스 사용자 인증 정보에서 사전 등록됨(사용자 위임 OAuth의 경우) 또는 머신 간(OAuth 클라이언트 사용자 인증 정보)을 선택하고 정적 클라이언트 ID 및 클라이언트 보안 비밀번호를 제공합니다.
OAuth 로그인 팝업이 차단되거나 비어 있음	도구 동기화 또는 테스트 중에 '브라우저에서 인증 팝업을 차단했습니다'라는 메시지가 표시되거나 OAuth 로그인 창이 제대로 표시되지 않습니다.	브라우저 팝업 차단기 또는 로그인 페이지의 엄격한 X-Frame-Options/Content-Security-Policy 헤더로 인해 팝업 흐름이 차단되었습니다.	브라우저에서 콘솔의 팝업을 허용한 후 다시 시도해 보세요. 개발자 인증 정보로 인증의 액세스 사용자 인증 정보에서 팝업을 통해 인증을 리디렉션을 통해 인증(대체)으로 전환하여 인증 흐름이 동일한 탭에서 전체 화면으로 열리도록 합니다.
MCP 서버 요청 사항 누락	경고 메시지: 'MCP 서버에 안내가 없습니다. 서버 스키마에 안내를 추가하는 것이 좋습니다."	MCP 서버가 initialize 응답에서 instructions 필드를 반환하지 않았습니다.	MCP 서버를 초기화할 때 시스템 요청 사항을 명시적으로 정의합니다(서버 정의의 instructions 매개변수). 스테이트리스(Stateless) 또는 커스텀 HTTP 구현의 경우 initialize 메서드의 JSON-RPC 응답 페이로드에 instructions 필드가 포함되어 있는지 확인한 다음 도구 다시 동기화를 선택합니다.
UI 리소스 크기 제한 또는 지원되지 않는 MIME 유형	가져오기 문제 오류 카드: '누적 리소스 크기는 100MB를 초과할 수 없습니다.' 또는 '<uri>' 리소스에 지원되지 않는 MIME 유형 '<type>'입니다.	MCP 서버에서 총 크기가 한도를 초과하거나 지원되지 않는 MIME 유형을 사용하는 UI 리소스를 반환했습니다.	서버에서 반환하는 모든 매니페스트 UI 리소스의 누적 크기를 줄여 한도를 초과하지 않도록 합니다. 모든 UI 리소스가 지원되는 MIME 유형(text/html, text/html;profile=mcp-app, text/javascript, text/css) 중 하나를 사용하는지 확인합니다.
아이콘 업로드가 중단되거나 '예기치 않은 오류'가 발생함	앱 세부정보에서 앱 아이콘을 업로드할 때 업로드가 로딩 스피너에서 멈추거나 '예기치 않은 오류가 발생했습니다. 다시 시도해 주세요.'(코드 4E696748가 함께 표시되는 경우가 많음)	일반적으로 오래된 브라우저 세션, 충돌하는 브라우저 확장 프로그램 또는 캐시된 인증 상태로 인해 발생합니다.	다음 단계를 순서대로 시도해 보세요. 새 브라우저 프로필 사용: 깨끗한 브라우저 프로필을 사용하여 새 창을 엽니다. 시크릿 모드/비공개 모드 사용: 시크릿 브라우징 창에서 Google Connected Console에 로그인하고 아이콘을 업로드합니다. 캐시 지우기: 다시 시도하기 전에 브라우저의 캐시와 쿠키를 지우고 아이콘이 1MB 미만의 유효한 512px × 512px PNG 또는 JPEG인지 확인합니다.