ujinify.com 워드프레스에 MCP Adapter가 코어에 내장돼 있다는 걸 알게 됐다. 나중에 밝혀졌지만, 이 이야기의 결론은 결국 세션 ID 하나였다.
거기에 랭크매스(워드프레스 SEO 플러그인)가 ability(어빌리티, 서버가 외부에 제공하는 기능 단위)를 25개나 등록해뒀다. get-seo-scores로 여러 글 점수를 한 번에 조회하거나, audit-site-seo/fix-site-seo로 사이트 전체를 진단하고 자동 수정하거나, set-homepage-seo로 설정까지 바꿀 수 있는 것들이었다.
그전까지는 SEO 점수 하나 확인하려면 Playwright(플레이라이트, 브라우저를 자동으로 조종하는 도구)로 wp-admin 에디터를 직접 열어야 했다. 이걸 Claude Code에 MCP 서버로 등록하면 API 호출 하나로 끝낼 수 있겠다 싶었다. 그래서 등록했다. 그리고 아무것도 안 됐다.
문제: MCP가 ‘연결됨’인데 tool이 하나도 안 보여요
등록 자체는 간단했다.
claude mcp add --transport http ujinify-wp <MCP 서버 URL> --header "Authorization: Basic ..."claude mcp list를 돌리면 “✔ Connected”가 떴다. 연결됐다는 뜻이다. 그런데 ToolSearch(툴서치, Claude Code에서 사용 가능한 도구를 찾는 기능)로 아무리 찾아봐도 랭크매스 tool(툴, 도구)이 하나도 잡히지 않았다. 매번 “No matching deferred tools found”였다. 세션을 새로 시작해봤다. 재시작도 해봤다. 결과는 똑같았다.
서버는 연결됐다는데, 실제로 쓸 수 있는 tool은 하나도 없는 상태. 이건 좀 웃겼다.
curl로 직접 테스트해보니 세션 ID가 필요했다
Claude Code를 믿지 않기로 했다. curl(컬, 터미널에서 HTTP 요청을 직접 보내는 도구)로 MCP 서버에 직접 말을 걸어보기로 했다.
먼저 initialize(초기화 요청, MCP 서버와 처음 악수하는 단계)를 호출했다. 서버는 정상 응답했다. 그런데 응답 헤더(header, 서버가 응답과 함께 보내는 부가 정보)를 보니 mcp-session-id라는 값이 딸려 내려왔다. 이 서버는 Streamable HTTP(스트리머블 HTTP, 요청마다 세션 ID를 주고받는 MCP 통신 방식)를 쓰는 타입이었다.
그 상태에서 세션 ID 없이 바로 tools/list를 호출했다. 결과는 “Missing Mcp-Session-Id header” 에러였다. 반대로, initialize에서 받은 세션 ID를 Mcp-Session-Id 헤더에 실어서 tools/list를 다시 호출했더니 — 랭크매스가 등록한 tool 3개의 스키마(schema, 도구의 구조와 사용법을 정의한 명세)가 정상으로 내려왔다.
서버는 100% 정상이었다. 문제는 Claude Code 쪽이었다.
왜 Claude Code는 세션 ID를 못 챙겼을까
MCP 통신은 핸드셰이크(handshake, 통신 시작 전에 서로 규칙을 맞추는 절차)가 필요하다. MCP 공식 스펙 문서에도 명시돼 있는 내용인데, 순서는 이렇다.
initialize요청을 보낸다.- 서버가 응답 헤더로 세션 ID를 내려준다.
- 이후 모든 요청에 그 세션 ID를
Mcp-Session-Id헤더에 실어서 보낸다.
Claude Code의 HTTP MCP 클라이언트가 이 두 번째와 세 번째 단계를 처리하지 못하고 있었다. initialize는 성공했지만, 거기서 받은 세션 ID를 이후 요청에 다시 실어 보내지 않는 것이다.
claude mcp list의 “Connected” 표시는 initialize 성공만 확인한다. 그러니 이 핸드셰이크 실패를 잡아내지 못하고, 겉으로는 정상처럼 보인다. 연결은 됐지만 실제로 아무것도 못 쓰는 상태가 “Connected”로 표시되는 것이다. 별로였다.
해결책: 직접 만든 함수로 세션 핸드셰이크 처리하기
MCP tool 등록에 기대는 걸 포기했다. 대신 이 핸드셰이크 절차를 그대로 코드로 옮겼다.
scripts/rankmath-mcp.ts에 callRankMathAbility 함수를 만들었다. 이 함수는 호출될 때마다 아래 순서를 자동으로 처리한다.
initialize요청을 보내서 세션 ID를 받는다.- 받은 세션 ID를 헤더에 실어서
tools/call을 호출한다. - 결과를 반환한다.
CLI(커맨드 라인 인터페이스, 터미널에서 명령어로 프로그램을 실행하는 방식)에서 바로 쓸 수 있게 npm run rankmath -- <ability-name> '<json-params>' 형태로도 만들었다. 기존 upload.ts의 getWpConfig()를 그대로 재사용해서 인증 정보를 따로 관리할 필요도 없게 했다.
Claude Code가 못 하는 걸 직접 구현한 것이다. 우아하진 않지만 동작한다.
실제로 점수를 가져왔을 때 검증 결과
get-seo-scores ability(어빌리티, 여기서는 랭크매스가 MCP를 통해 제공하는 기능)를 호출해서 여러 글의 점수를 한 번에 받아봤다. 이전에 Playwright로 wp-admin 에디터를 직접 열어서 확인했던 점수와 정확히 일치했다. 132번 글 81점, 109번 글 83점, 42번 글 79점. 숫자가 맞았다.
그다음엔 실제로 사이트 전체를 점검했다. seo_filter를 bad(50점 이하), empty-fk(포커스 키워드 없음), unscored(채점 안 됨)로 각각 돌렸다. 결과는 깔끔했다. 문제되는 글은 하나도 없었다. 포커스 키워드가 없는 건 애초에 필요 없는 고정 페이지 3개뿐이었다.
브라우저를 한 번도 열지 않았다. 몇 초 만에 끝났다.
이 방법의 한계, 읽기만 되고 쓰기는 안 된다
명확히 해둬야 할 게 있다.
get-seo-scores는 데이터베이스에 이미 저장된 점수를 ‘읽기’만 한다. 랭크매스의 점수 계산 엔진 자체는 여전히 브라우저, 구체적으로는 wp-admin 에디터의 자바스크립트에서만 돌아간다. 새 글을 올리거나 콘텐츠를 수정한 직후에 점수를 새로 계산하려면 여전히 에디터를 열어야 한다. REST나 MCP로는 재계산을 트리거할 방법이 없다.
analyze-post-content라는 ability도 있다. 이건 점수를 주지 않는다. 원본 콘텐츠와 24개 테스트 목록, 채점 기준 문서를 던져주고 AI가 직접 채점하라는 방식이다. 손이 많이 가서 아직 시도하지 않았다.
결국 이 방법으로 해결된 건 ‘이미 채점된 점수를 빠르게 읽는 것’이다. 채점 자체는 여전히 브라우저 의존이다. 한계를 알고 쓰면 된다. 모르고 쓰면 나중에 헷갈린다.
다음에는 analyze-post-content를 실제로 써볼 생각이다. AI가 직접 채점한 결과가 랭크매스 공식 점수와 얼마나 차이 나는지 비교해보면 쓸만한지 아닌지 판단할 수 있을 것이다.
“설정 화면에 값이 있다고 실제로 작동한다는 보장은 없다”는 패턴은 이번에도 반복됐다. 워드프레스 SEO 버그 5개 총정리 글에서 다룬 다섯 가지 사례와 정확히 같은 결이다. 이번엔 랭크매스 설정이 아니라 Claude Code의 MCP 연결 상태였다는 것만 다르다.
세션 쪽에서 겪은 또 다른 문제는 Claude 5시간 한도 72% 찍힌 이유는 세션 길이였다에도 있다.