Inspo MCP 사용법: 디자인 레퍼런스와 스크린샷을 Claude Code·Codex UI 개발에 활용하기

Claude Code나 Codex에 “깔끔하고 고급스럽고 디자인이 좋은 랜딩 페이지를 만들어 달라”고 요청하면, 작동하는 페이지를 얻는 것 자체는 어렵지 않습니다. 문제는 결과물이 익숙한 그라데이션 배경, 둥근 카드, 큰 제목으로 끝나는 경우가 많고, 실제로 참고하고 싶었던 레이아웃과 리듬, 시각적 위계는 제대로 반영되지 않는다는 점입니다.

Inspo는 이보다 구체적인 문제를 해결합니다. 에이전트가 UI 코드를 작성하기 전에 실제 웹사이트에서 가져온 디자인 레퍼런스를 먼저 제공할 수 있습니다. 공식 사이트에는 현재 운영 중인 웹사이트 832개, 데스크톱과 모바일 캡처가 포함된 페이지 기록 2,320개, 레퍼런스 컴포넌트 68개가 안내되어 있으며, 페이지에서 추출한 색상 팔레트, 폰트, 간격, 모서리 반경, 컨테이너 폭, 페이지 구조 정보도 제공합니다. 이 자료는 MCP를 통해 Claude Code, Codex 같은 클라이언트에 전달됩니다.

하지만 설치가 끝났다고 해서 에이전트가 스크린샷을 봤다는 뜻은 아니며, 최종 페이지에 레퍼런스가 반영됐다는 의미는 더더욱 아닙니다. 더 신뢰할 수 있는 작업 흐름은 다음과 같습니다.

1. Inspo MCP를 연결하고 클라이언트가 실제로 연결됐는지 확인합니다.
2. 곧바로 코드를 작성시키지 말고, 먼저 레퍼런스를 검색하게 합니다.
3. 어떤 페이지 기록과 이미지 URL을 받았는지, 이미지를 실제로 읽었는지 확인합니다.
4. 선택한 레퍼런스를 명확한 “레퍼런스 계약”으로 정리합니다.
5. 구현 후 실제 렌더링을 확인하고 항목별로 비교한 뒤 수정합니다.

아래에서는 “기존 프로젝트에 개발자 대상 B2B 제품 랜딩 페이지를 만든다”는 가상의 작업을 예로 듭니다. 이 예시는 작업 방법을 설명하기 위한 것이며, 이 글이 여러분의 프로젝트를 실제로 실행하거나 테스트했다는 뜻은 아닙니다.

Inspo MCP가 실제로 제공하는 것

Inspo는 단순한 스크린샷 검색기가 아닙니다. 공식 MCP 페이지와 프로젝트 저장소에 따르면 에이전트는 세 가지 종류의 레퍼런스 자료를 받을 수 있습니다.

1. 페이지와 스크린샷

search_screens는 자연어, 스타일, 업종, 페이지 유형, 색상, 라이트·다크 모드, 페이지 구조를 기준으로 실제 페이지를 찾을 수 있습니다. 결과에는 다음 정보가 포함될 수 있습니다.

• 페이지 제목, Inspo slug, 원본 웹사이트 주소
• 데스크톱 및 모바일 스크린샷 URL
• 페이지 썸네일
• 색상 팔레트, 폰트, 기술 스택, 태그
• 페이지의 전체적인 특징과 섹션 구조 분석

특정 후보를 자세히 살펴볼 때는 많은 후보를 한꺼번에 컨텍스트에 넣기보다 get_screen으로 해당 페이지의 더 자세한 기록을 가져오는 편이 좋습니다.

2. 구조화된 디자인 시스템

수집된 각 웹사이트에는 페이지 정보를 바탕으로 생성된 DESIGN.md가 있습니다. get_design_system은 폰트, 의미 기반 색상, 글자 크기 체계, 간격, 모서리 반경, CSS 변수, 컨테이너 폭 등의 정보를 반환할 수 있습니다.

이런 데이터가 중요한 이유는 “이 사이트를 참고해 달라”는 지시가 너무 모호하기 때문입니다. 반면 “첫 화면은 좌우 2열로 구성하고, 본문 컨테이너 폭을 제한하며, 주요 버튼에는 대비가 높은 강조색을 쓰고, 섹션 사이에는 충분한 여백을 둔다” 같은 요구사항은 에이전트가 훨씬 안정적으로 실행할 수 있습니다.

3. 레퍼런스 컴포넌트와 코드

Inspo는 내비게이션, Hero, 가격, 푸터 등 다양한 레퍼런스 컴포넌트도 제공합니다. 에이전트는 먼저 find_reference_components로 적절한 컴포넌트를 찾고, 이어서 get_reference_jsx로 해당 JSX를 가져올 수 있습니다.

그렇다고 전체 사이트를 그대로 복사해야 한다는 뜻은 아닙니다. 컴포넌트의 구성 방식과 정보 계층을 참고하되 현재 프로젝트의 기술 스택, 브랜드, 콘텐츠, 인터랙션에 맞게 다시 설계하는 것이 바람직합니다.

처음에는 recommend를 사용하는 것이 가장 좋습니다. 자연어로 요구사항을 전달하면 페이지 구조, 후보 웹사이트, 레퍼런스 컴포넌트, 색상 팔레트, 레이아웃 제안을 함께 제공합니다. 처음부터 열 개가 넘는 페이지를 연속으로 검색하기보다는 에이전트가 recommend를 먼저 호출한 뒤 후보 한두 개를 자세히 살펴보게 하는 편이 대체로 효율적입니다.

모델 연결과 Inspo MCP는 서로 다른 경로입니다

Claude Code나 Codex가 코드를 분석하고 수정하고 추론하려면 정상적인 모델 연결이 필요합니다. Inspo MCP는 외부 디자인 자료를 제공합니다. 두 경로는 주소, 인증 방식, 장애 원인이 서로 다릅니다.

이미 BetterToken을 통해 Claude Code나 Codex를 사용하고 있다면 먼저 해당 문서에 따라 모델 연결을 완료합니다.

• Claude Code 연결 문서
• Codex 연결 문서

그다음 Inspo를 별도로 설정합니다. https://inspomcp.dev/api/mcp를 모델의 Base URL로 입력하거나 BetterToken API Key를 Inspo에 제공하지 마세요. Inspo의 공식 호스팅 엔드포인트는 현재 계정이나 API Key를 요구하지 않습니다. BetterToken은 Inspo를 호스팅하지 않고, 제3자 디자인 자료에 대한 권리를 제공하지 않으며, 에이전트가 반드시 이미지를 읽거나 특정 UI 결과를 만들 것이라고 보장하지도 않습니다.

연결 전에 다음만 확인하면 됩니다.

• Claude Code 또는 Codex가 설치되어 있고 일반적인 코딩 작업을 수행할 수 있습니다.
• 클라이언트가 Inspo의 호스팅 주소에 접근할 수 있습니다.
• 자동 설치 도구나 로컬 stdio 방식을 사용할 경우 Node.js와 npx를 사용할 수 있습니다.

Inspo MCP 연결하기

Inspo는 자동 설치 도구를 제공하며, 각 클라이언트의 MCP 명령을 직접 사용할 수도 있습니다. 여러 AI 코딩 도구가 설치된 컴퓨터라면 먼저 --dry-run을 실행해 어떤 클라이언트와 설정이 변경되는지 확인하는 것이 좋습니다.

방법 1: Inspo 자동 설치 도구 사용

설정을 쓰지 않고 Claude Code만 확인합니다.

npx -y inspo-mcp install --dry-run --client claude-code

계획을 확인한 뒤 설치합니다.

npx -y inspo-mcp install --client claude-code

Codex만 확인합니다.

npx -y inspo-mcp install --dry-run --client codex

확인 후 설치합니다.

npx -y inspo-mcp install --client codex

--client를 지정하지 않으면 설치 도구가 Claude Code, Codex, Cursor, VS Code, Windsurf, Claude Desktop, Zed의 설치 여부를 감지합니다. Inspo MCP 공식 안내에 따르면 먼저 계획을 보여 주고 확인을 요청합니다. --dry-run은 계획만 출력하고 파일을 쓰지 않으며, -y는 확인 절차를 건너뜁니다.

방법 2: 호스팅 MCP 직접 추가

Inspo가 권장하는 호스팅 엔드포인트는 다음과 같습니다.

https://inspomcp.dev/api/mcp

공식 저장소는 Inspo를 읽기 전용 서비스로 설명하지만, 여전히 외부 제3자 MCP입니다. 팀 환경에서는 연결 전에 저장소, 데이터 범위, 네트워크 정책을 확인해야 합니다. “읽기 전용”이라는 이유로 신뢰 검토를 생략해서는 안 됩니다.

Claude Code 공식 MCP 문서에 따르면 원격 서비스는 HTTP 방식으로 추가해야 합니다. 모든 로컬 프로젝트에서 Inspo를 사용하려면 다음을 실행합니다.

claude mcp add --scope user --transport http inspo https://inspomcp.dev/api/mcp

이후 상태를 확인합니다.

claude mcp get inspo
claude mcp list

Claude Code 세션 안에서는 다음도 사용할 수 있습니다.

/mcp

Added는 설정이 기록됐다는 뜻일 뿐입니다. 실제 연결 상태는 claude mcp list에서 확인해야 하며, Connected가 표시돼야 연결된 것입니다. Failed to connect, Pending approval, 비활성 상태라면 먼저 해결해야 합니다.

OpenAI의 Codex MCP 문서는 Codex가 Streamable HTTP와 STDIO 서비스를 지원한다고 설명합니다. 원격 MCP는 다음과 같이 추가합니다.

codex mcp add inspo --url https://inspomcp.dev/api/mcp

설정된 서비스를 확인합니다.

codex mcp list

Codex 대화형 화면에서도 다음을 사용할 수 있습니다.

/mcp

OpenAI의 현재 문서에 따르면 Codex CLI, IDE 확장 프로그램, ChatGPT 데스크톱 앱은 같은 Codex 호스트에서 실행될 때 MCP 설정을 공유합니다. 서비스를 추가하거나 변경한 뒤에는 현재 클라이언트를 재시작하거나 새 세션을 열고 Inspo가 나타나는지 확인하세요.

stdio는 전송 방식의 대안일 뿐입니다

클라이언트에서 원격 URL에 연결하기 어렵다면 npx를 통해 stdio 서비스를 실행할 수 있습니다.

claude mcp add --scope user inspo -- npx -y inspo-mcp

codex mcp add inspo -- npx -y inspo-mcp

자동 설치 명령에 --local을 추가할 수도 있습니다. 하지만 이 방식도 Inspo 카탈로그를 CDN에서 가져오므로 오프라인 실행이나 완전한 자체 호스팅과 같지는 않습니다.

처음 사용할 때는 코드를 쓰기 전에 레퍼런스부터 찾으세요

가장 흔한 실수는 “레퍼런스 찾기”와 “페이지 구현하기”를 한 문장으로 합치는 것입니다.

Inspo를 사용해 멋진 랜딩 페이지를 만들어 주세요.

이렇게 지시하면 에이전트가 레퍼런스를 직접 선택하고, 무엇을 가져올지 결정한 뒤 곧바로 코드를 작성합니다. 결과가 좋지 않더라도 검색 결과가 부적절했는지, 스크린샷이 컨텍스트에 들어오지 않았는지, 구현 단계에서 레퍼런스와 멀어졌는지 판단하기 어렵습니다.

첫 번째 프롬프트는 다음처럼 분리하는 편이 안전합니다.

아직 코드를 수정하거나 페이지 디자인을 시작하지 마세요.

Inspo MCP를 사용해 “개발자 대상 B2B AI API 제품 랜딩 페이지”를 위한 후보 레퍼런스 4개를 찾아 주세요.

요구사항:
- 넓은 영역에 화려한 그라데이션을 쓰지 않고 절제되고 전문적인 인상을 줄 것
- Hero에서 제품 가치를 명확하게 설명하고 주요 CTA 하나를 포함할 것
- 제품 인터페이스나 호출 흐름을 보여 줄 수 있지만 전통적인 기업 웹사이트처럼 보이지 않을 것
- 데스크톱과 모바일 레퍼런스를 모두 확인할 것
- 먼저 recommend를 사용하고, 필요한 경우에만 search_screens, get_screen, get_design_system을 사용할 것

각 후보에 대해 다음을 반환해 주세요.
1. 페이지 제목, Inspo slug, sourceUrl
2. 도구 결과에 존재하는 경우 데스크톱 및 모바일 스크린샷 URL
3. macrostructure, 주요 색상 팔레트, 폰트
4. 참고할 가치가 있는 구체적인 디자인 포인트 3개
5. 복사해서는 안 되는 브랜드 요소, 문구, 장식

마지막에는 주요 레퍼런스 하나와 보조 레퍼런스 최대 두 개만 추천하고, 각각 무엇을 담당할지 설명하세요. 아직 코드를 작성하지 마세요.

이 프롬프트의 목적은 형용사를 더 많이 얻는 것이 아니라 추적 가능한 페이지 식별자와 근거를 받는 것입니다. “현대적이고 깔끔하며 전문적”이라는 요약만이 아니라 구체적인 slug, 원본 사이트 주소, 스크린샷 URL, 디자인 데이터가 보여야 합니다.

에이전트가 레퍼런스를 실제로 받았는지 확인하는 방법

검증은 네 단계로 나눌 수 있습니다. 앞 단계가 성립한다고 해서 다음 단계까지 자동으로 성립하는 것은 아닙니다.

단계	관찰 가능한 증거	증명되는 내용
MCP 설정 확인됨	Claude Code에 Connected가 표시되거나 Codex MCP 목록에 Inspo가 있음	Connected는 Claude Code의 연결을 확인해 줌. Codex 목록은 설정이 존재한다는 뜻이며, 서비스 접근은 성공적인 도구 호출로 확인해야 함
도구가 자료를 반환함	응답에 실제 slug, sourceUrl, 색상, 폰트, 페이지 구조, 스크린샷 URL이 있음	에이전트가 Inspo를 호출해 구조화된 기록을 받았음
이미지가 읽힘	에이전트가 이미지를 읽을 수 있는 도구로 스크린샷 URL을 열거나 사용 가능한 이미지 뷰어를 이용하고 구체적인 시각 요소를 설명함	텍스트 설명이나 링크만 읽은 것이 아님. 결과에 썸네일이 있다는 사실만으로는 이미지 읽기를 증명할 수 없음
페이지에 레퍼런스가 반영됨	실제 렌더링과 선택한 레퍼런스 사이에 구조, 계층, 리듬, 반응형 동작의 설명 가능한 대응이 있음	레퍼런스가 구현에 실제로 영향을 줌

이 구분은 중요합니다. Inspo의 응답 형식에는 항상 구조화된 텍스트가 포함되며 원본 이미지 URL이 함께 올 수 있습니다. 지원되는 경로에서는 썸네일을 네이티브 이미지 콘텐츠 블록으로 도구 결과에 넣을 수도 있습니다. 그러나 프로젝트의 응답 형식 구현은 두 가지 다른 경우도 명시적으로 처리합니다. 이미지 가져오기에 실패하면 텍스트와 URL은 남지만 이미지 블록이 생략될 수 있고, 텍스트 우선 설정에서는 텍스트만 반환될 수도 있습니다.

따라서 “에이전트가 스크린샷 URL을 반환했다”는 사실만으로 모델이 픽셀을 읽었다고 볼 수 없습니다. 다음과 같은 검증 프롬프트를 보냅니다.

먼저 주요 레퍼런스를 실제로 받았다는 것을 증명하세요. 아직 코드를 작성하지 마세요.

다음을 출력해 주세요.
- 이번 세션에서 실제로 사용한 Inspo 도구 이름
- 주요 레퍼런스의 slug, sourceUrl, 데스크톱 스크린샷 URL, 모바일 스크린샷 URL
- 데스크톱과 모바일 스크린샷에서 각각 관찰한 구체적인 시각적 사실 3개. 예: Hero 구성, 내비게이션 위치, CTA 정렬, 이미지 크롭, 카드 배열, 접힘 방식
- 어떤 결론이 스크린샷에서 나온 것이고, 어떤 결론이 Inspo의 텍스트 필드에서만 나온 것인지

현재 클라이언트가 텍스트나 URL만 받았고 이미지 픽셀을 읽지 않았다면 “이미지 픽셀을 읽지 않았음”이라고 명시하세요. 설명을 바탕으로 시각적 세부 사항을 추측하지 마세요.

이상적인 결과는 긴 디자인 평론이 아닙니다. “화면에 실제로 있는 요소”와 “구조화된 데이터가 제공한 결론”을 분리해서 설명할 수 있어야 합니다.

에이전트가 색상, 폰트, northstar 설명만 반복한다면 현재 클라이언트에서 사용할 수 있는 브라우저나 이미지 읽기 도구로 스크린샷 URL을 열게 하세요. 현재 클라이언트와 모델이 이미지 입력을 지원한다면 스크린샷을 다운로드해 이미지로 첨부할 수 있습니다. 모델이나 제공업체 경로가 이미지를 처리하지 못한다면 파일 첨부로 해결되지 않습니다. Inspo를 구조·색상·텍스트 분석에 사용하거나, 이미지 입력을 지원하는 구성으로 전환하세요. MCP가 이미지를 반환할 수 있다고 해서 모든 클라이언트와 모델 조합이 이미지를 처리하는 것은 아닙니다.

레퍼런스를 “레퍼런스 계약”으로 정리하기

후보를 정한 다음에도 “A의 느낌을 참고해 달라”는 말로 끝내서는 안 됩니다. 각 레퍼런스가 무엇을 담당하는지 정하고, 무엇을 복사하면 안 되는지 명확히 해야 합니다.

에이전트에게 다음과 같은 계약을 만들게 할 수 있습니다.

확인된 주요 레퍼런스와 보조 레퍼런스를 바탕으로 먼저 “레퍼런스 계약”을 정리하세요. 아직 코드를 수정하지 마세요.

다음을 포함하세요.

1. 주요 레퍼런스
- slug / sourceUrl:
- 담당 범위: 전체 페이지 구조, Hero 구성, 섹션 리듬만

2. 보조 레퍼런스 A
- slug / sourceUrl:
- 담당 범위: 글자 계층, 본문 폭, 여백만

3. 보조 레퍼런스 B(정말 필요한 경우에만)
- slug / sourceUrl:
- 담당 범위: 특정 컴포넌트 하나 또는 모바일 접힘 방식만

4. 현재 프로젝트에서 반드시 유지할 것
- 기존 기술 스택, 라우팅, 컴포넌트 규칙
- 실제 제품 문구, 기능 범위, 브랜드 색상
- 기존 인터랙션, 접근성 요구사항, 성능 요구사항

5. 명시적으로 금지할 것
- 원본 사이트의 로고, 브랜드명, 일러스트, 사진, 원문을 복사하지 않음
- 사이트 전체를 픽셀 단위로 복제하지 않음
- 레퍼런스에 맞추기 위해 현재 제품에 없는 기능을 만들지 않음

6. 인수 기준
- 일반적인 데스크톱 viewport에서 Hero가 제목, 설명, CTA, 주요 비주얼을 모두 전달함
- 정보 계층은 주요 레퍼런스를 따르지만 내용은 현재 제품에 속함
- 모바일에서는 명확한 재배치 규칙을 적용하며 데스크톱 레이아웃을 축소만 하지 않음
- 섹션 여백, 컨테이너 폭, 글자 계층, 버튼 우선순위에 검증 가능한 규칙이 있음

레퍼런스 계약은 영감을 제약 조건으로 바꿉니다. 주요 레퍼런스는 전체 구조를 담당하고, 보조 레퍼런스는 일부 문제만 해결합니다. 레퍼런스가 많다고 항상 좋은 것은 아닙니다. 다섯 사이트가 색상, 폰트, 카드, Hero를 동시에 좌우하면 우선순위가 없는 전형적인 AI 스타일 페이지로 돌아가기 쉽습니다.

Claude Code 또는 Codex가 구현을 시작하게 하기

레퍼런스와 인수 기준을 확인한 뒤 에이전트가 저장소를 살펴보고 코드를 수정하게 합니다. 아래 프롬프트는 npm run dev, 프레임워크 디렉터리, 테스트 명령을 일부러 고정하지 않습니다. 이런 정보는 추측하지 말고 현재 프로젝트에서 판단해야 하기 때문입니다.

이제 구현을 시작하세요.

먼저 현재 저장소의 기술 스택, 페이지 진입점, 디자인 변수, 재사용 가능한 컴포넌트, 사용 가능한 스크립트를 확인하세요. 그런 다음 확인된 “레퍼런스 계약”에 따라 페이지를 수정하세요.

구현 요구사항:
- 기존 프레임워크, 컴포넌트 체계, 의존성을 사용하고 정말 필요한 경우가 아니라면 새 UI 프레임워크를 추가하지 않을 것
- 실제 제품 콘텐츠와 기능을 유지하고 레퍼런스 사이트의 브랜드 자산이나 문구를 복사하지 않을 것
- 레퍼런스를 현재 프로젝트 고유의 레이아웃, CSS 변수, 컴포넌트로 변환할 것
- 데스크톱과 모바일을 모두 의도적으로 구현하고, 모바일을 마지막에 남겨 자동 축소에만 맡기지 않을 것
- 그림자, 모서리 반경 같은 장식보다 전체 구조, 정보 계층, 간격을 먼저 수정할 것
- Inspo가 JSX를 제공한다는 이유만으로 기존 프로젝트 컴포넌트를 덮어쓰지 않을 것

파일을 수정하기 전에 다음을 짧게 설명하세요.
1. 수정할 파일
2. 각 레퍼런스 포인트가 반영될 컴포넌트 또는 스타일 규칙
3. 변경하지 않고 유지해야 하는 기존 콘텐츠

완료 후:
- 저장소에 이미 있는 포맷 검사, 타입 검사 또는 테스트를 실행할 것
- 사용 가능한 로컬 미리보기를 실행할 것
- 실제로 수정한 파일을 나열할 것
- “레퍼런스 포인트 → 구현 위치” 대응표를 출력할 것
- “더 현대적”, “더 고급스러움” 같은 표현만으로 결과를 평가하지 않을 것

프로젝트에 이미 디자인 토큰이 있다면 여러 컴포넌트에 색상과 치수를 하드코딩하기보다 먼저 토큰이나 의미 기반 변수를 수정하게 하세요. 그러면 다음 반복에서 페이지 전체 리듬을 더 빠르게 조정할 수 있습니다.

최종 판단은 코드 diff가 아니라 실제 렌더링을 기준으로 해야 합니다

페이지가 컴파일된다는 사실은 코드가 실행된다는 것만 증명합니다. 레퍼런스가 반영됐는지 판단하려면 실제 페이지를 확인해야 합니다.

Inspo 페이지에는 일반적으로 데스크톱과 모바일 캡처가 있습니다. 공식 Colophon은 아카이브가 1440픽셀과 375픽셀 폭으로 캡처된다고 설명합니다. 높이를 정확히 맞출 필요는 없지만 비슷한 폭으로 구현 결과를 보면 전체 구조와 모바일 재배치를 비교하기 쉽습니다.

Claude Code나 Codex에 브라우저, Playwright 또는 다른 스크린샷 도구가 이미 설정되어 있다면 에이전트가 로컬 페이지를 열게 하세요. 그렇지 않다면 직접 브라우저에서 미리보기를 열고 데스크톱·모바일 화면을 캡처한 뒤 에이전트에게 전달합니다.

다음 형식으로 검토하게 하세요.

다음을 비교하세요.
- 확인된 주요 레퍼런스의 데스크톱 및 모바일 스크린샷
- 현재 페이지를 약 1440px 및 375px 폭에서 실제로 렌더링한 스크린샷

아직 재설계하거나 코드를 수정하지 마세요. 먼저 차이 표를 출력하세요.

| 확인 항목 | 레퍼런스에서 관찰 가능한 증거 | 현재 구현 | 차이 | 권장 수정 |
| --- | --- | --- | --- | --- |
| Hero 구조 |  |  |  |  |
| 제목과 CTA 계층 |  |  |  |  |
| 컨테이너와 여백 |  |  |  |  |
| 글자 계층 |  |  |  |  |
| 색상과 대비 |  |  |  |  |
| 컴포넌트 배열 |  |  |  |  |
| 모바일 재배치 |  |  |  |  |

그다음 영향이 가장 큰 차이 3개만 골라 수정하세요. 수정 후 다시 렌더링하고 재검토하세요. 같은 단계에서 새로운 디자인 방향을 추가하지 마세요.

좋은 수정 의견은 관찰 가능하고 실행 가능해야 합니다. 예를 들면 다음과 같습니다.

• 나쁜 예: “Hero가 아직 충분히 고급스럽지 않습니다.”
• 좋은 예: “주요 레퍼런스는 첫 viewport 안에 제목, CTA, 제품 인터페이스를 모두 보여 줍니다. 현재 페이지는 세로 여백이 너무 커서 제품 인터페이스가 첫 화면 아래로 밀려납니다. Hero의 세로 간격을 줄이고 제목 폭을 제한하며, 일반적인 데스크톱 높이 안에 주요 비주얼이 나타나게 하세요.”

또 다른 예입니다.

• 나쁜 예: “모바일 버전이 레퍼런스와 충분히 비슷하지 않습니다.”
• 좋은 예: “모바일 레퍼런스는 제목과 CTA를 먼저 보여 준 뒤 단일 열 제품 카드를 배치합니다. 현재 구현은 데스크톱의 2열 레이아웃을 유지해 텍스트와 이미지가 모두 좁아집니다. 모바일에서는 1열로 바꾸고 CTA가 주요 비주얼보다 먼저 나오게 하세요.”

매 단계에서 영향이 큰 차이 몇 개만 수정하는 편이 “더 예쁘게 만들어 달라”고 반복하는 것보다 빠르게 수렴합니다.

자주 발생하는 문제

설정 명령은 성공했지만 에이전트가 Inspo를 찾지 못함

재설치하기 전에 클라이언트 상태부터 확인하세요.

Claude Code:

claude mcp get inspo
claude mcp list

Codex:

codex mcp list

엔드포인트에 불필요한 문자가 없는지 확인하고 클라이언트를 재시작하세요. Claude Code에서 프로젝트 수준의 .mcp.json을 사용한다면 신뢰할 수 있는 워크스페이스에서 서비스를 승인해야 할 수도 있습니다.

MCP는 연결됐지만 에이전트가 Inspo를 호출하지 않음

검색 단계와 코딩 단계를 분리하세요. 프롬프트에 “먼저 Inspo를 호출해 slug, sourceUrl, 스크린샷 URL을 반환하고, 레퍼런스가 확인되기 전에는 코드를 수정하지 말 것”이라고 명시합니다. /mcp에서 서비스가 활성화됐는지도 확인하세요.

페이지 설명은 반환됐지만 이미지가 보이지 않음

호출이 텍스트만 반환했거나, 썸네일 가져오기에 실패했거나, 클라이언트가 MCP 이미지 블록을 표시하지 않거나, 모델 경로가 이미지를 처리하지 않을 수 있습니다. 데스크톱과 모바일 스크린샷 URL이 남아 있는지 확인하고, 에이전트가 픽셀을 읽었는지 명확히 말하게 하세요. 현재 클라이언트와 모델이 이미지 입력을 지원한다면 브라우저 도구로 URL을 열거나 스크린샷을 첨부하세요. 텍스트 전용 모델이라면 구조화된 데이터를 사용하거나 이미지를 처리할 수 있는 구성으로 전환하세요.

페이지가 여전히 흔한 템플릿처럼 보임

일반적으로 레퍼런스를 열 개 더 찾는 것이 해결책은 아닙니다. 주요 레퍼런스 하나가 전체 구조를 담당하고, 보조 레퍼런스 하나가 글자와 여백을 담당하며, 또 하나를 쓴다면 특정 컴포넌트만 담당하도록 범위를 좁히세요. 이를 계약에 기록하고 에이전트에게 “레퍼런스 포인트 → 코드 위치” 대응을 요구합니다.

컨텍스트가 너무 커져 에이전트가 레퍼런스를 혼동함

recommend로 후보를 얻은 뒤 선택한 한두 개에만 get_screen 또는 get_design_system을 호출하세요. 많은 전체 페이지 기록과 컴포넌트 소스를 한꺼번에 로드하지 마세요. 특정 컴포넌트가 필요할 때만 get_reference_jsx를 사용합니다.

원본 사이트가 Inspo 스크린샷과 달라짐

Inspo는 캡처 당시 페이지 자료를 저장하지만, 원본 사이트는 이후 개편될 수 있습니다. 비교할 때는 선택한 Inspo 스크린샷과 기록을 기준으로 하세요. sourceUrl은 출처를 추적하기 위한 것이며, 원본 사이트가 언제나 아카이브와 같은 모습이라고 가정하면 안 됩니다.

중요한 것은 “MCP 설치”가 아니라 증거의 연결고리를 만드는 것입니다

Inspo MCP의 가치는 좋은 디자인을 자동으로 결정해 주는 데 있지 않습니다. “이런 느낌을 원한다”는 요구를 추적 가능한 페이지, 스크린샷, 디자인 데이터, 레퍼런스 컴포넌트로 바꾸는 데 있습니다.

신뢰할 수 있는 UI 개발 한 사이클에는 네 종류의 증거가 남아야 합니다.

1. 클라이언트가 Inspo 연결을 확인합니다.
2. 에이전트가 구체적인 페이지와 디자인 자료를 반환합니다.
3. 에이전트가 스크린샷을 읽었음을 확인할 수 있거나, 텍스트만 받았다고 솔직히 밝힙니다.
4. 최종 렌더링에서 어떤 구조·계층·반응형 규칙이 레퍼런스에서 왔는지 항목별로 설명할 수 있습니다.

검색, 확인, 구현, 재검증을 분리하면 Claude Code나 Codex는 더 이상 “감으로 보기 좋은 페이지를 만드는” 데 그치지 않습니다. 확인하고 수정하고 재사용할 수 있는 디자인 컨텍스트 안에서 작업하게 됩니다.