wp-mcp-gateway (Cloudflare Workers 버전)

Node 버전과 같은 아이디어입니다: 하나의 MCP 엔드포인트, 모든 도구 호출이 site_id를 받으므로, 하나의 Claude 커넥터가 WordPress 사이트 전체를 포괄합니다. 이 버전은 VPS 대신 Cloudflare Workers에서 실행됩니다 — 패치할 서버가 없고, 무료 티어가 이를 충분히 감당하며, wrangler deploy를 실행한 지 몇 분 안에 workers.dev URL에서 라이브로 운영됩니다.

Cloudflare의 현재 권장 방식을 기반으로 구축되었습니다: agents SDK의 stateless createMcpHandler (기존의 stateful McpAgent / Durable Objects 방식은 새 서버에서는 더 이상 권장되지 않습니다 — 이 게이트웨이는 어차피 세션 상태가 필요 없습니다, 모든 도구 호출이 독립적이기 때문입니다).

인계 전에 로컬에서 엔드투엔드로 검증했습니다: Worker가 기동하고, /health가 응답하고, MCP initialize 핸드셰이크가 작동하며, 베어러 토큰 인증이 누락/잘못된 토큰을 올바르게 거부하고 올바른 토큰을 허용하며, list_sites가 테스트 SITES_JSON에서 실제 데이터를 반환합니다.

1. 전제 조건

npm install -g wrangler   # or just use npx wrangler as shown below
wrangler login            # opens a browser to authenticate with your Cloudflare account

아직 Cloudflare 계정이 없다면 다음에서 무료로 가입하세요 https://dash.cloudflare.com/sign-up — 무료 티어(하루 100,000건 요청)는 이 용도로 충분합니다.

2. 의존성 설치

cd wp-mcp-gateway-cf
npm install

3. 사이트 구성

Node 버전과 달리 Workers에는 파일 시스템이 없으므로 사이트 레지스트리는 파일 대신 시크릿(SITES_JSON)에 저장됩니다. 이전과 동일한 형태입니다 — 사이트당 항목 하나:

{
  "town-green": {
    "label": "Town Green",
    "baseUrl": "https://town-green.org",
    "username": "mcp-agent",
    "appPassword": "xxxx xxxx xxxx xxxx xxxx xxxx",
    "host": "wpengine"
  },
  "cra": {
    "label": "CRA",
    "baseUrl": "https://cra.com",
    "username": "mcp-agent",
    "appPassword": "xxxx xxxx xxxx xxxx xxxx xxxx",
    "host": "gridpane"
  }
}

모든 사이트에 대해 해당 JSON을 생성하세요 (각 사이트에 Application Passwords를 생성한 후 스프레드시트를 JSON으로 변환하는 스크립트는 쉽게 만들 수 있습니다 — 필요하면 요청하세요), 그런 다음 시크릿으로 설정하세요:

npx wrangler secret put SITES_JSON
# paste the whole JSON blob when prompted, then press Ctrl+D

Application Passwords: wp-admin에서 Users → your user → Application Passwords. 이전과 동일한 권장사항 — 개인 관리자 계정 대신 사이트별로 전용 저권한 WP 사용자를 사용하세요. 유출된 토큰이 해당 역할이 허용하는 것 이상을 할 수 없도록 하기 위해서입니다.

4. 게이트웨이 인증 토큰 설정

npx wrangler secret put GATEWAY_TOKEN
# paste a long random value, e.g. output of: openssl rand -hex 32

이것을 설정하지 않으면 엔드포인트는 인증 없이 실행됩니다 — 첫 로컬 테스트에는 괜찮지만 배포 버전에서는 절대 안 됩니다.

5. 로컬 테스트

npx wrangler dev

이렇게 하면 로컬 개발 서버(기본값 http://localhost:8787)가 시작됩니다. 로컬 테스트의 경우 시크릿을 .dev.vars 파일에 넣으세요 (절대 커밋하지 마세요):

GATEWAY_TOKEN=some-local-test-token
SITES_JSON={"town-green":{"label":"Town Green","baseUrl":"https://town-green.org","username":"mcp-agent","appPassword":"xxxx"}}

작동 여부 확인:

curl http://localhost:8787/health

6. 배포

npx wrangler deploy

Wrangler가 라이브 URL을 출력합니다, 다음과 같이:

https://wp-mcp-gateway.<your-subdomain>.workers.dev

MCP 엔드포인트는 https://wp-mcp-gateway.<your-subdomain>.workers.dev/mcp입니다.

7. Claude에서 커넥터로 추가

해당 /mcp URL을 가리키는 사용자 지정 커넥터를 추가하고, 헤더에 Authorization: Bearer <GATEWAY_TOKEN>를 설정하세요 (4단계에서 설정한 값과 동일).

그때부터 "cra.com의 임시글 목록" 작업은 Claude가 list_sites를 호출하거나(또는 id를 이미 알고 있거나) 그런 다음 list_posts를 site_id: "cra"로 호출하기만 하면 됩니다 — Node 버전과 동일한 동작이며, 다만 엣지에서 호스팅됩니다.

나중에 사이트 업데이트

새 사이트를 추가하거나 자격 증명을 변경하려면 다음을 다시 실행하세요:

npx wrangler secret put SITES_JSON

재배포가 필요 없습니다 — 시크릿은 Worker 코드와 독립적으로 업데이트됩니다.

이 배포에 특정한 참고 사항

• 파일 시스템 없음, 장기 실행 프로세스 없음 — 전체 레지스트리는 SITES_JSON 시크릿에 저장되며, 각 요청 시 새로 파싱됩니다. ~80개 사이트에서조차 비용은 미미합니다.

• 설계상 stateless — 각 MCP 요청은 새 서버 인스턴스를 생성합니다(Cloudflare의 현재 지침에 따라); 손실될 크로스 요청 세션이 없습니다.

• 관리형 호스트의 WAF 플래그 — Node 버전과 동일한 주의사항: 특히 WP Engine은 REST API를 호출하는 익숙하지 않은 IP 범위의 트래픽을 플래그할 수 있습니다. 어떤 사이트가 이 게이트웨이를 통할 때만 403을 반환한다면, WP Engine 지원팀에 확인해야 할 첫 번째 사항입니다 — 필요하다면 Cloudflare의 이그레스 범위를 허용 목록에 추가할 가치가 있습니다.

• 도구 범위 — 핵심 WP REST API(/wp/v2/...)와만 통신합니다. WP-CLI, SSH, 데이터베이스 수준 작업은 없습니다 — Workers는 어차피 SSH로 나갈 수 없으므로, 나중에 필요하다면 완전히 별도의 구성 요소가 필요할 것입니다.

Claude를 배포된 URL에 연결하기 전 보안 체크리스트

• GATEWAY_TOKEN이 wrangler secret put으로 설정되어 있고, 길고 무작위인지

• SITES_JSON이 사이트별로 전용 저권한 WP 사용자를 사용하는지

• .dev.vars(로컬에서 사용한 경우)가 .gitignore에 있고 커밋되지 않았는지

• 시크릿을 전체 ~80개로 확장하기 전에 2–3개 사이트에서 테스트했는지