Claude Code에 SEO MCP 서버를 추가하는 방법

Claude Code는 이미 파일을 편집하고, 명령어를 실행하며, 코드베이스를 통해 추론할 수 있습니다.

하지만 작업이 실시간 외부 시스템에 의존할 때 격차가 발생합니다.

SEO(검색 엔진 최적화)가 좋은 예시입니다. Claude Code에게 랜딩 페이지를 개선해 달라고 요청하면, 페이지를 검사하고 더 나은 카피를 제안할 수 있습니다. 하지만 사용자가 데이터를 직접 붙여넣지 않는 한, 현재의 SERP(검색 엔진 결과 페이지), 경쟁 페이지의 형식, AI Overview(AI 개요) 동작 또는 백링크(backlink) 맥락을 알 수는 없습니다.

그것이 바로 MCP가 만들어진 목적입니다.

Claude Code의 MCP 문서는 MCP 서버를 Claude Code를 외부 도구, 데이터베이스 및 API에 연결하는 방법으로 설명합니다. 이를 통해 Claude는 복사된 데이터로 작업하는 대신 해당 시스템을 직접 읽고 조작할 수 있습니다.

이 가이드에서는 Claude Code에 SEO MCP 서버를 추가하고 첫 번째 유용한 프롬프트를 실행해 보겠습니다.

저는 AgentSEO를 예시 서버로 사용하겠습니다. AgentSEO는 호스팅된 Streamable HTTP MCP 엔드포인트와 로컬 npm 패키지를 제공하기 때문입니다. 설정 패턴이 중요한 부분입니다.

SEO MCP 서버를 통해 얻을 수 있는 것

SEO MCP 서버는 Claude Code에 실시간 검색 워크플로우에 대한 도구 접근 권한을 부여합니다.

다음과 같이 묻는 대신:

여기 SERP 내보내기 데이터가 있습니다. 요약해 줄 수 있나요?

이렇게 요청할 수 있습니다:

SEO MCP 서버를 사용하여 미국의 "best seo api"에 대한 SERP를 분석해 줘.
그 다음 검색 의도(search intent)를 파악하고 비교 페이지를 위한 콘텐츠 브리프(content brief) 초안을 작성해 줘.

문구의 차이는 작지만 워크플로우의 차이는 매우 큽니다.

첫 번째 프롬프트는 당신을 데이터 파이프라인으로 만듭니다.

두 번째 프롬프트는 Claude Code가 도구를 직접 호출하게 합니다.

AgentSEO의 경우, 현재 라이브 서버 카드는 SERP 분석, 키워드 아이디어, 콘텐츠 브리프, 로컬 SEO 점검, 백링크 분석, 순위 추적 및 AI Overview 추출을 포함하여 45개의 MCP 도구를 나열하고 있습니다.

직접 확인할 수 있습니다:

curl https://www.agentseo.dev/.well-known/mcp/server-card.json

호스팅된 엔드포인트는 다음과 같습니다:

시작하기 전에

세 가지가 필요합니다:

• Claude Code 설치 완료
• AgentSEO API 키
• MCP 서버를 사용하고자 하는 프로젝트

서버 측 API 키를 사용하세요. 로컬 에이전트 도구 (agent tooling) 용도로 브라우저 제한 키 (browser-restricted key)를 사용하지 마세요.

옵션 1: 호스팅된 SEO MCP 서버 추가하기

Claude Code는 다음과 같이 원격 HTTP MCP 서버를 지원합니다:

claude mcp add --transport http <name> <url>

AgentSEO의 경우:

claude mcp add --transport http agentseo https://www.agentseo.dev/mcp \
  --header "Authorization: Bearer sk_live_your_key" \
  --header "x-project-id: client-alpha" \
...

sk_live_your_key를 귀하의 AgentSEO API 키로 교체하세요.

x-project-id 및 x-workflow-id 헤더는 선택 사항이지만, 저는 초기에 추가하는 것을 선호합니다. 에이전트 워크플로 (agent workflow)가 실제 API 호출을 시작하게 되면 추적 가능성 (traceability)이 중요해지기 때문입니다.

옵션 2: 로컬 npm MCP 서버 추가하기

로컬 stdio 서버를 선호한다면 npm 패키지를 사용하세요:

{
  "mcpServers": {
    "agentseo": {
...

이는 MCP 클라이언트가 호스팅된 HTTP 엔드포인트 대신 로컬 서브프로세스 (subprocess)를 기대할 때 유용합니다.

모든 것을 로컬에 유지해야 할 특별한 이유가 없다면, 저는 Claude Code에서 호스팅된 HTTP 버전을 먼저 시작할 것입니다.

Claude Code에서 서버 확인하기

서버를 추가한 후, Claude Code를 열고 다음을 실행하세요:

/mcp

Claude Code의 /mcp 패널을 통해 연결된 MCP 서버를 검사할 수 있습니다. 서버와 해당 도구 (tools)들이 표시되어야 합니다.

서버가 나타나지 않는 경우:

• Claude Code 재시작
• API 키 헤더 확인
• 엔드포인트 URL이 정확히 https://www.agentseo.dev/mcp인지 확인
• claude mcp list 실행
• claude mcp get agentseo 실행

Claude Code가 도구들을 볼 수 있을 때까지 설정은 완료된 것이 아닙니다.

첫 번째 프롬프트: 실시간 SERP 분석

하나의 제한된 워크플로 (workflow)로 시작하세요.

Use AgentSEO to analyze the SERP for "best seo api" in the United States.

Return:
...

이는 단순히 “SEO 조언을 해줘”라고 요청하는 것보다 훨씬 낫습니다. 이 프롬프트는 키워드, 위치, 출력 형태, 그리고 당신이 필요로 하는 결정 사항을 명시하고 있습니다.

두 번째 프롬프트: 콘텐츠 브리프 (content brief) 생성

SERP 분석이 제대로 작동한다면, 실제 제작 단계에 더 가까운 것을 요청해 보세요.

Use AgentSEO to create a content brief for the keyword "seo api for ai agents".

Audience: developers building agent workflows.
...

“무엇을 주장하지 말아야 하는지 (what not to claim)”라는 문구가 중요합니다. 에이전트가 생성한 SEO 콘텐츠는 모든 도구의 출력값을 마케팅적 확신으로 바꿔버릴 때 위험해질 수 있습니다.

Claude Code에게 검토 단계를 유지하도록 요청하세요.

세 번째 프롬프트: AI 개요 (AI Overview) 가시성 확인

만약 당신의 SEO 작업이 AI 검색과 관련이 있다면, 더 좁은 범위의 프롬프트를 사용하세요.

Use AgentSEO to check AI Overview visibility for "best seo api".

Tell me:
...

이를 마법 같은 순위 상승 버튼이 아니라, 방향성을 잡기 위한 조사 (directional research)로 취급하세요.

AI 개요의 동작 방식은 계속 변합니다. 핵심은 일회성 스크린샷이 아니라, 반복 가능한 확인 절차를 만드는 것입니다.

흔한 설정 실수

짜증 나는 MCP 실패 원인은 대개 사소한 것들입니다.

잘못된 헤더 (header) 형식

다음과 같이 사용하세요:

--header "Authorization: Bearer sk_live_your_key"

CLI 명령에 헤더를 JSON 형식으로 붙여넣지 마세요.

잘못된 전송 방식 (transport)

호스팅된 AgentSEO 엔드포인트의 경우, 다음을 사용하세요:

--transport http

MCP 명세(spec)에서는 현재 HTTP 전송 방식을 Streamable HTTP라고 부릅니다. Claude Code는 CLI에서 http를 허용하며, JSON 설정에서는 streamable-http도 인식합니다.

설정 후 재시작 불필요

Claude Code가 이미 열려 있었다면, 서버를 추가한 후 재시작하거나 /mcp를 다시 확인하세요.

프롬프트가 너무 모호함

다음은 좋지 않은 첫 번째 프롬프트입니다:

내 SEO를 개선해줘.

다음은 더 나은 첫 번째 프롬프트입니다:

AgentSEO를 사용하여 미국의 "best seo api"에 대한 SERP (검색 엔진 결과 페이지)를 분석하고, 내가 어떤 페이지 유형을 구축해야 하는지 알려줘.

MCP는 Claude Code에 도구 (tools)를 제공합니다. 하지만 여전히 당신은 Claude Code에게 할 일을 부여해야 합니다.

SEO MCP 서버를 사용하지 말아야 할 때

모든 글쓰기 작업에 SEO MCP 서버를 사용하지 마세요.

다음과 같은 경우에는 실시간 SEO 도구가 필요하지 않을 가능성이 높습니다:

• 브랜드 보이스 (brand voice)를 편집할 때
• 문법을 교정할 때
• 내부 문서 (internal docs)를 작성할 때
• 저장소 (repo)에 이미 소스 데이터가 있는 경우
• 페이지가 검색 중심이 아닌 경우

결정이 현재의 검색 컨텍스트 (search context)에 달려 있을 때 서버를 사용하세요.

여기에는 SERP 의도 (intent), 경쟁사 페이지 형태, 키워드 기회, AI 개요 (AI Overview) 가시성, 순위 추적 (rank tracking), 로컬 가시성, 또는 백링크 신호가 포함됩니다.

운영자 체크리스트

설정이 완료되었다고 판단하기 전에 다음을 확인하세요:

• MCP 서버를 추가했는가.
• /mcp에 나타나는지 확인했는가.
• 실시간 SERP 프롬프트를 한 번 실행했는가.
• 실제 제작 형태의 콘텐츠 브리프 (content brief) 프롬프트를 한 번 실행했는가.
• 작동하는 프롬프트를 저장소 (repo)나 팀 문서에 저장했는가.
• 여러 사람이 사용할 경우 프로젝트/워크플로우 메타데이터를 추가했는가.
• 결과물이 배포되기 전에 누가 SEO 권장 사항을 검토할지 결정했는가.

마지막 단계가 중요합니다.

SEO MCP 서버는 Claude Code에 더 신선한 컨텍스트를 제공합니다. 그것이 판단력을 없애주지는 않습니다.

최선의 워크플로우는 "에이전트가 쓰고, 사람이 게시한다"가 아닙니다.

더 나은 워크플로우는 다음과 같습니다:

에이전트가 실시간 SEO 컨텍스트를 수집함
에이전트가 권장 사항 초안을 작성함
사람이 트레이드오프 (tradeoffs)를 확인함
...

이 지점에서 MCP가 유용하게 느껴지기 시작합니다.

또 다른 대시보드로서가 아니라,

이미 작업이 이루어지고 있는 곳 내부의 도구 계층 (tool layer)로서 말입니다.

링크

• Claude Code MCP 문서: [https://code.claude.com/docs/en/mcp]
• MCP 전송 사양 (transport spec): [https://modelcontextprotocol.io/specification/2025-06-18/basic/transports]
• AgentSEO Claude Code 통합: [https://www.agentseo.dev/integrations/claude-code]
• AgentSEO MCP 랜딩 페이지: [https://www.agentseo.dev/seo-mcp-server]
• AgentSEO npm 패키지: [https://www.npmjs.com/package/@agentseo/mcp-server]