MCP 도구 이름은 보이는데 아이콘만 비어 있다면, 서버 연결을 다시 설정하기 전에 도구 메타데이터와 호스트의 이미지 표시 기능을 나눠 확인하세요. 목록에 도구가 있다는 사실과 그림이 화면에 표시된다는 사실은 서로 다른 관측입니다. 아이콘을 고치려고 인증 권한을 넓히거나 보안 차단을 해제할 필요는 없습니다.
적용 기준은 MCP 2026-07-28입니다. 공식 문서를 확인한 날짜는 2026년 10월 11일이며, 특정 앱이나 SDK 버전에서 재현한 장애 보고서는 아닙니다. 아래 진단 순서와 기록 양식은 운영을 위한 제안이고, JSON은 형식을 설명하는 가상 예시입니다.
먼저 아이콘 표시를 지원하는 화면인지 확인합니다
공식 규격에서 icons는 선택 메타데이터입니다. 아이콘을 렌더링하는 클라이언트는 PNG·JPEG를 지원해야 하고, SVG·WebP 지원은 권고입니다. 이 조건은 모든 호스트가 모든 화면에 아이콘을 표시한다는 보장이 아닙니다. 공식 icons 규격
같은 앱에서도 서버 연결 목록과 개별 도구 선택창을 구분해 관찰하세요. 연결 목록의 로고가 정상이라는 이유로 도구마다 별도 아이콘을 그리는 화면이라고 단정하면 잘못된 부분을 고치게 됩니다. 먼저 현재 호스트의 도움말과 실제 화면에서 어느 위치의 아이콘을 지원하는지 확인하고, 확인하지 못했다면 지원 여부를 미확인으로 남깁니다.
빈 그림을 다섯 단계로 좁히는 순서
다음 표는 오류 원인을 미리 정한 목록이 아닙니다. 위쪽 단계에서 관측이 확인되면 다음 단계로 넘어가는 점검 순서입니다. 처음부터 파일을 변환하거나 서버를 재설치하면 어느 변경이 효과를 냈는지 비교하기 어렵습니다.
| 관측 | 다음 확인 |
|---|---|
| 도구 자체가 목록에 없다 | 이 글의 아이콘 진단보다 tools/list 응답과 목록 페이지네이션을 먼저 확인 |
| 도구는 있지만 icons 항목이 없다 | 호스트가 받은 해당 도구 정의에 icons가 실제 포함됐는지 확인 |
| icons는 있지만 이미지 요청이 없다 | 호스트의 표시 지원, URL 정책, 캐시 여부를 나누어 확인 |
| 요청은 있으나 이미지 대신 로그인 화면이 온다 | 응답 본문과 리다이렉트 목적지를 확인. 인증값을 아이콘 요청에 붙이지 않기 |
| 정상 이미지인데 화면에서는 안 보인다 | 밝은·어두운 배경, 크기, 투명도, 실패 시 대체 표시를 비교 |
개발자 도구나 진단 로그를 볼 수 있다면 상태 코드만 기록하지 마세요. 최종 응답의 형식, 실패 단계, 요청 시각도 함께 남깁니다. 접근할 수 없는 환경에서는 “서버가 잘못됐다”로 채우지 말고 해당 관측을 미확인으로 표시하는 편이 정확합니다.
도구 정의에 들어갈 JSON 조각
공식 tools/list 예시에서 아이콘 배열은 개별 도구 객체에 들어갑니다. 다음은 그 배열만 발췌한 형식 예시입니다. 전체 JSON-RPC 요청이나 실행 가능한 서버 코드가 아닙니다. example.com 주소는 실제 이미지가 아니므로 그대로 붙여 넣으면 작동하지 않습니다.
{ "icons": [ { "src": "https://example.com/assets/notes-light.png", "mimeType": "image/png", "sizes": [ "48x48" ], "theme": "light" }, { "src": "https://example.com/assets/notes-dark.png", "mimeType": "image/png", "sizes": [ "48x48" ], "theme": "dark" } ]}
src는 필수이며 mimeType, sizes, theme는 선택입니다. sizes는 문자열 배열이고, theme은 그림이 놓일 밝은 배경 또는 어두운 배경을 가리킵니다. 테마를 생략하면 어느 테마에도 쓸 수 있는 것으로 취급합니다. 2026-07-28 타입 스키마
실제 적용 시에는 자신이 관리하는 MCP 서버와 같은 출처의 이미지로 바꾸고, 파일 이름만 바꿔 비교하지 말고 호스트가 새 메타데이터를 받아들였는지도 확인하세요. 다크 모드에서만 빈칸처럼 보인다면 네트워크 장애보다 그림과 배경의 대비를 먼저 비교할 이유가 있습니다. 이것은 진단 우선순위에 대한 제안이며, 특정 앱의 원인을 확인했다는 뜻은 아닙니다.
로그인이 필요한 이미지로 해결하려 하지 않습니다
규격의 보안 요구는 아이콘 메타데이터와 파일을 신뢰하지 않는 입력으로 다루는 것입니다. HTTPS 또는 data URI를 사용하며 위험한 스킴과 다른 출처로의 리다이렉트를 차단하고, 쿠키나 Authorization 헤더 없이 가져옵니다. 실제 파일과 MIME 형식을 확인하고, 과도한 크기·픽셀 수·프레임 수로 인한 자원 고갈에 방어해야 합니다. 구체적인 크기 한도를 두는 방식은 규격이 허용하는 선택지입니다. SVG는 실행 가능한 내용을 포함할 수 있어 별도의 주의가 필요합니다. 아이콘 보안 고려사항
예를 들어 가상의 메모 도구가 로그인한 브라우저에서는 열리는 이미지를 아이콘으로 등록했다고 해봅시다. 호스트가 인증 없이 요청하면 로그인 페이지를 받을 수 있습니다. 이때 해결 후보는 인증 토큰을 복사하는 일이 아니라, 공개해도 되는 전용 아이콘을 안전한 경로로 제공하는 것입니다. 고객 화면 캡처나 비공개 문서를 로고 대용으로 올리지 마세요.
같은 이름의 PNG 두 개를 비교할 때도 파일 확장자만 보지 않습니다. 호스트가 HTML 오류 페이지를 이미지로 받는 경우와, 실제 PNG가 너무 커서 거절되는 경우는 수정 위치가 다릅니다. 브라우저의 보안 경고를 무시하거나 이미지 검증을 끄면 화면은 달라져도 원래 문제를 안전하게 해결했다고 할 수 없습니다.
복사해서 남길 최소 진단 기록
확인 시각 / 시간대:호스트 이름과 실제 버전:서버·SDK의 실제 버전:사용한 MCP revision:확인한 화면: 서버 목록 / 도구 목록 / 기타해당 도구의 icons 포함 여부:이미지 요청 여부 / 최종 응답 형식:출처 일치 / 리다이렉트 여부:밝은·어두운 테마에서 관측한 차이:수정한 항목 한 가지:수정 뒤 같은 조건에서 다시 확인한 결과:아직 확인하지 못한 범위:
실제 로그를 붙일 때는 인증 헤더, 쿠키, 서명된 URL의 비밀 쿼리, 고객 자료를 제거하세요. 지원 문의에는 필요한 최소 항목만 공유하면 됩니다. 관측하지 않은 앱 버전이나 패키지 버전은 임의로 채우지 않습니다.
어디까지 확인해야 끝난 걸까요
이 글이 권하는 완료 조건은 “이미지 URL이 열린다”보다 구체적입니다. 실제 대상 호스트의 대상 화면에서 도구 이름과 아이콘이 함께 보이고, 사용하는 테마에서 구분되며, 이미지가 실패해도 도구 이름과 실행 판단 정보가 남는지 확인합니다. 모바일을 지원하는 제품이라면 좁은 화면에서도 같은 조건을 확인하세요. 화면 확인을 못 했다면 메타데이터 점검까지 마쳤다고 범위를 적습니다.
여기서는 특정 호스트의 표시 성공이나 SDK 호환성을 시험하지 않았습니다. 프로토콜 문서의 설명과 진단 제안을 분리해 사용하세요. 도구 자체가 빠져 있다면 도구 목록 페이지네이션 점검으로 돌아가고, 도구의 안전성을 판단하려면 annotations 힌트의 범위를 함께 읽어보세요. 예쁜 아이콘은 실행 권한이나 도구의 신뢰성을 증명하지 않습니다.