문서 › MCP 레퍼런스 › MCP 서버

MCP 서버

MCP Server

Model Context Protocol 클라이언트(Claude Desktop, Claude Code, Cursor, Windsurf, VS Code)에서 4개의 네이티브 도구 및 6개의 워크플로우 프롬프트로 FourA를 사용하세요. 통합 코드나 사용자 지정 HTTP 클라이언트가 필요 없습니다.

GitHub의 오픈 소스이며, npm에서 @fouradata/mcp(으)로 제공됩니다. 현재 릴리스: 0.5.0.

빠른 시작: 로컬 stdio (Claude Desktop 권장)

foura.ai/dashboard#api-keys에서 키를 가져오세요(클릭 한 번으로 생성 시 한 번만 표시됨, 형식 pk_live_...). 이를 MCP 클라이언트의 config에 추가하세요:

{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "@fouradata/mcp"],
      "env": { "FOURA_API_KEY": "pk_live_..." }
    }
  }
}

Claude Desktop 주의 사항: 설정 파일을 편집하기 전에 Claude Desktop을 완전히 종료하십시오(macOS의 경우 Cmd+Q). 앱이 여전히 실행 중인 경우 종료 시 메모리에 있는 설정으로 편집 내용을 덮어씁니다.

npx 명령어는 첫 실행 시 @fouradata/mcp을(를) 다운로드하고 MCP 클라이언트의 하위 프로세스로 실행합니다. 전역 설치가 필요하지 않습니다.

클라이언트 설정 파일 위치
Claude Desktop (macOS) ~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows) %APPDATA%\Claude\claude_desktop_config.json
Claude Code claude mcp add foura -- npx -y @fouradata/mcp (먼저 환경에서 FOURA_API_KEY 설정)
Cursor ~/.cursor/mcp.json
Windsurf ~/.codeium/windsurf/mcp_config.json
VS Code (MCP extension) .vscode/mcp.json

클라이언트를 다시 시작하십시오. 도구 목록에 도구(foura_auto, foura_single, foura_proxy, foura_browser)와 6개의 프롬프트가 나타납니다.

빠른 시작: 호스팅(Streamable HTTP)

Streamable HTTP 전송을 지원하는 클라이언트(Cursor, Windsurf, VS Code, --transport http을(를) 사용하는 Claude Code)의 경우 로컬 하위 프로세스를 실행하는 대신 호스팅된 endpoint를 가리키도록 하십시오:

{
  "mcpServers": {
    "foura": {
      "url": "https://mcp.foura.ai/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_..."
      }
    }
  }
}

Claude Desktop의 경우 위의 stdio config를 사용하거나 mcp-remote을 통해 호스팅된 endpoint를 연결하십시오:

{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.foura.ai/mcp", "--header", "Authorization: Bearer pk_live_..."]
    }
  }
}

호스팅 엔드포인트 참조

속성 값
URL https://mcp.foura.ai/mcp
전송 스트리밍 가능한 HTTP (POST /mcp, SSE 응답)
인증 요청당 Authorization: Bearer pk_live_...
MCP-Protocol-Version @modelcontextprotocol/sdk에 따름 (현재 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07)
401 챌린지 WWW-Authenticate: Bearer realm="foura-mcp", resource_metadata="https://foura.ai/docs/mcp/server#auth"

호스팅 서버는 상태를 저장하지 않습니다(stateless). 모든 요청은 자체 키를 포함하며, 서버는 이를 X-API-Key로 FourA API에 전달합니다. 키 하나로 4개의 도구를 모두 사용할 수 있습니다.

DNS 리바인딩(CVE-2025-66414)을 방지하기 위해 서버는 Host 헤더(mcp.foura.ai 또는 localhost여야 함)와 존재하는 경우 Origin 헤더를 검증합니다(허용 목록: mcp.foura.ai, claude.ai, app.cursor.sh, app.cursor.com). 서버 간 호출자(stdio 브릿지 모드의 curl, MCP 클라이언트)는 Origin를 보내지 않고 통과합니다.

도구

4개의 도구는 모두 MCP 2025-06-18 사양에 따라 readOnlyHint: true 및 openWorldHint: true으로 주석 처리됩니다. 신뢰할 수 있는 읽기 전용 도구를 자동 승인하는 클라이언트는 요청별 확인 모달 없이 도구를 호출합니다.

foura_auto은 스마트 기본값입니다. URL을 제공하면 패치 메서드를 선택하여 콘텐츠를 반환합니다. 나머지 3개는 이를 조정하는 하위 수준 프리미티브이며, 명시적인 제어가 필요할 때 사용합니다.

foura_auto

FourA가 요청 메서드를 선택하게 하려면 URL을 제공하십시오. 사용 가능한 HTTP, 프록시, 브라우저 경로에서 제한된 횟수만큼 시도합니다. 보호된 대상에서는 응답이 실제 페이지를 식별하는 콘텐츠를 포함하도록 validate을 전달하십시오. 유효성 검사를 통과하는 시도가 없으면, 챌린지 페이지를 성공으로 제시하는 대신 오류를 반환합니다.

응답은 meta에 완료 세부 정보를 포함하며, 기본적으로 proxy, cookies, userAgent을 포함하는 재사용 가능한 session을 제공합니다. 일반적인 후속 조치의 경우 proxy으로 session.proxy를 전달하여 foura_single를 호출하고, 쿠키를 Cookie 헤더로 직렬화하며, session.userAgent을 User-Agent 헤더로 전송합니다. JavaScript 렌더링의 경우 세션 값을 일치하는 foura_browser 필드에 전달하십시오.

foura_single

하나의 HTTP 요청과 응답을 반환합니다. POST /api/single/와 1대1로 일치합니다.

정적 페이지, JSON API, 서버 렌더링 HTML에 사용합니다.

제공할 브라우저 선택

요청은 기본적으로 최신 Google Chrome을 제공합니다. 대상이 특정 브라우저만 수락하고 다른 브라우저를 거부하는 경우, browser (Chrome, Edge, Safari, Firefox 또는 Tor), os (Windows, macOS, Android 또는 iOS), version를 설정하거나 정확한 profile id를 전달하십시오:

{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}

여러 프로필이 일치하면 최신 버전이 우선 적용됩니다. 존재하지 않는 조합은 사용 가능한 목록과 함께 오류를 반환하므로 선택하지 않은 브라우저로 request가 전송되지 않습니다. 선택에는 unblocker이 필요하며 기본적으로 켜져 있습니다. 카탈로그는 GET /api/profiles에 게시되며 API 키가 필요하지 않습니다.

동일한 4개의 필드가 foura_proxy의 request 객체 안에 있습니다.

foura_proxy

자동 재시도 기능을 갖춘 순환 proxy를 통해 단일 HTTP request를 라우팅합니다. foura_single이 차단되었거나 대상이 특정 송신 국가를 요구할 때 사용합니다.

exitCountries을 사용자 또는 대상 요구 사항에 따라 제공되는 대상 표시용 2자리 국가 코드의 엄격한 허용 목록으로 설정합니다:

{
  "maxTries": 5,
  "exitCountries": ["CZ", "GB"],
  "request": {
    "method": "GET",
    "url": "https://example.com/pricing",
    "browser": "Chrome",
    "os": "Windows"
  }
}

값은 트리밍, 대문자 변환, 중복 제거가 수행됩니다. 알 수 없는 exit을 가진 프록시는 제외되며, request는 요청하지 않은 국가로 fallback되지 않습니다. 프록시 선택에는 일반적으로 10분 이내에 업데이트되는 최신 타겟 가시적(target-visible) 국가 메타데이터가 사용되며, request 중 실시간 지리적 위치 조회를 수행하지 않습니다. 프록시 호스트 주소로 서비스 국가를 유추하지 마십시오.

스코프가 지정된 성공은 exitCountry 및 재사용 가능한 proxy ID를 반환합니다. exitCountry이 요청된 allowlist에 속하는지 확인하십시오. 현재 풀에 일치하는 항목이 없으면 도구는 details.exitCountries에 정규화된 스코프가 포함된 code: "no_eligible_proxy"을 반환합니다. 해당 스코프를 유지하고 나중에 재시도하십시오. 사용자가 명시적으로 요구 사항을 변경할 때만 스코프를 변경하거나 확장하십시오.

선택한 페이지에 나중에 JavaScript가 필요한 경우, 브라우저가 동일한 exit을 재사용하도록 반환된 proxy ID를 foura_browser.proxy에 전달하십시오.

foura_browser

전체 브라우저 세션입니다. JavaScript가 실행되고, DOM이 렌더링되며, cookie가 반환됩니다. POST /api/browser/를 미러링합니다.

단일 페이지 앱, 지연 로드(lazy-loaded) 콘텐츠, 또는 통과하기 위해 실제 브라우저가 필요한 안티 봇 챌린지 뒤의 페이지에 사용하십시오.

각 도구의 입력 형태, 기본값, 유효성 검사 규칙은 REST endpoint 레퍼런스를 참조하십시오. 도구 스키마는 REST API와 필드 단위로 일치하며, MCP 전용 offload_large 옵트인(아래 참조)이 추가로 포함됩니다.

대상이 봇 검사를 실행할 때

본문(body)을 요청하는 동안 대상이 봇 검사를 실행하면 foura_single 및 foura_proxy는 defense을 반환합니다. defense.solved: true은 검사를 통과했으며 data이 실제 페이지임을 의미합니다. false는 본문이 챌린지 페이지일 수 있음을 의미합니다. 챌린지 페이지를 콘텐츠로 처리하는 대신, 다른 브라우저, OS 또는 버전으로 재시도하거나 foura_proxy 또는 foura_browser로 단계를 올리십시오.

타입이 지정된 response

모든 도구의 response에는 content(사람이 읽을 수 있는 텍스트 요약)와 structuredContent(해당 도구의 outputSchema에 대해 검증된 타입이 지정된 JSON)이 모두 포함됩니다. 각 도구에는 다음과 같은 고유한 형태가 있습니다.

  • foura_auto: 단일 형태의 { status, headers, data }와 meta(항상 존재하는 { rung, solved, attempts, credits }, 여기서 rung는 cache, probe, proxy, browser, fail 중 하나임) 및 기본적으로 더 낮은 레벨의 도구를 통한 재생(replay)을 위한 session({ proxy, cookies, userAgent })가 포함됩니다. total_time은 없습니다.
  • foura_single: { status, headers, data, total_time, ... } (header는 리디렉션 홉당 하나의 항목을 갖는 배열입니다)
  • foura_proxy: single과 동일하며 { proxy, total }이 추가됩니다. 스코프가 지정된 성공(scoped success)에는 exitCountry도 포함됩니다.
  • foura_browser: 고유한 형태 { status, headers: object, body, cookies, userAgent } (참고: body는 콘텐츠 타입에 따라 문자열 또는 객체일 수 있습니다)

structuredContent을 지원하는 클라이언트는 LLM이 산문에서 JSON을 파싱하도록 요구하는 대신, 타입이 지정된 객체를 LLM에 직접 전달할 수 있습니다.

다중 값 response header

여러 번 나타나는 header(Set-Cookie, Link, WWW-Authenticate)는 배열로 반환됩니다.

{
  "headers": [
    {
      "result": { "version": "HTTP/2", "code": 200, "reason": "" },
      "content-type": "text/html",
      "set-cookie": ["a=1; Path=/", "b=2; Path=/"]
    }
  ]
}

이는 하나의 response에서 session + tracking + consent cookie를 설정하는 사이트(대부분의 e-commerce)에서 중요합니다.

대용량 response: offload_large (기본값: inline)

기본적으로(v0.2.0부터) 전체 response body는 크기에 관계없이 structuredContent에 inline으로 반환됩니다. 이는 모든 MCP client에서 즉시 작동합니다.

client가 MCP resources/read을 지원하고 대용량 페이지에서 token을 절약하려면, 도구 호출마다 offload_large: true를 전달하십시오. 50 KB 이상의 response는 디스크에 기록되어 resource_link로 반환되며, client는 body가 실제로 필요할 때만 이를 가져옵니다. 캐시된 payload는 1시간 후 만료됩니다.

{
  "method": "GET",
  "url": "https://en.wikipedia.org/wiki/Web_scraping",
  "offload_large": true
}
클라이언트 offload_large: true
Claude Desktop 아직 지원 안 됨, 기본값 유지 false
Claude Code, Cursor, Windsurf 지원됨
VS Code MCP extension 지원됨

테넌트 격리: 각 API key는 자체 네임스페이스를 갖습니다(sha256(apiKey)[:16]). 페이로드를 저장한 key만 이를 다시 읽을 수 있습니다. 교차 테넌트 읽기는 존재 여부 누출 없이 Payload not found을 반환합니다.

내장 프롬프트

6개의 워크플로 템플릿이 모든 MCP 클라이언트의 /prompts 아래에 표시됩니다. 각각은 명명된 인수를 받아 하나 이상의 도구를 오케스트레이션하는 템플릿화된 사용자 메시지를 반환합니다.

프롬프트 인수 기능
smart_fetch url, 선택 사항 must_contain, extract Auto fetch(메서드 선택, 봇 보호 처리) 후 콘텐츠 반환 또는 추출
scrape_product_page url Browser fetch 후 제품 제목, 가격, 이미지, 재고, SKU를 JSON으로 추출
extract_article url Proxy 폴백과 함께 Single 처리 후 내비게이션 및 광고를 제거하고 깔끔한 기사 JSON 반환
monitor_pricing url, 선택 사항 target_price Proxy fetch, 현재 가격 추출, 목표와 비교
check_endpoint_health url, 선택 사항 expected_text 엄격한 유효성 검사를 포함한 Single 처리, 도달 가능성 및 타이밍 반환
bulk_fetch_urls urls (쉼표로 구분) 병렬 Single 처리, URL별 proxy 자동 폴백, 메타데이터만 반환

유휴 상태에서 프롬프트는 0 token을 소모합니다. 호출된 프롬프트만 LLM 컨텍스트에 포함됩니다.

전체 텍스트 및 수동 폴백 프롬프트: MCP Recipes.

Error envelope

모든 오류(isError: true)에는 structuredContent envelope가 포함됩니다. 모든 오류의 최소 필드:

{
  "service": "auto | single | proxy | browser",
  "code": "rate_limited",
  "error": "Rate limit exceeded"
}

HTTP status가 포함된 upstream 오류 시, status도 함께 존재합니다. rate limit 및 용량 오류 시, upstream 엔벨로프는 retryAfter, current.{concurrency, rpm} 및 limits.{maxConcurrency, maxRpm}를 추가합니다. 기본 REST 형태는 API Errors를 참조하십시오.

안정적인 code 값:

Code HTTP 의미 재시도 안전?
ssrf_blocked n/a 대상 IP가 사설 또는 예약된 대역에 있음(RFC 5735, 6598, IPv6 예약) 아니오, URL 변경
upstream_non_json varies Upstream이 잘못된 형식의 body를 반환함 아마도, 조사 필요
output_validation_failed n/a MCP 서버의 outputSchema이 upstream response를 거부함(서버 버그 또는 예상치 못한 upstream 형태) 아마도, 보고 요망
bad_request 400 입력 형태 거부됨 아니오, 인수 수정
auth_failed 401 Key 누락, 유효하지 않음 또는 비활성화됨 아니오, Key 수정
forbidden 403 인증되었으나 허용되지 않음 아니오, 또는 foura_proxy로 전환
not_found 404 대상 또는 endpoint 누락 아니오
rate_limited 429 RPM 제한 도달 예, retryAfter 대기
at_capacity 503 동시성 제한 도달 예, retryAfter 대기
service_disabled 503 유지보수 기간이거나 요금제에 이 도구가 포함되어 있지 않음 지원팀 문의
service_unavailable 503 일반적인 503 예, 짧은 백오프
upstream_error 500+ Upstream 5xx 예, 지수 백오프
upstream_client_error 4xx 기타 4xx 대체로 아니오
upstream_unknown other 방어적 코드, 실제로는 발생하지 않아야 함 조사 필요
no_eligible_proxy n/a 엄격한 exitCountries scope와 일치하는 proxy가 없음 나중에 재시도, 명시적으로만 scope 변경

LLM 에이전트는 산문을 파싱할 필요 없이 재시도 로직을 위해 code를 직접 읽을 수 있습니다. 인증 가이드: Authentication.

제한 사항

  • 기본적으로 inline body를 사용합니다. offload_large: true를 사용하면 50KB 이상의 response는 디스크 + resource_link(테넌트당, 1시간 TTL)로 이동합니다.
  • MCP 계층에서 사설 대상(RFC 5735, RFC 6598, IPv6 예약 블록)은 거부됩니다. 공개 호스트만 전달됩니다.
  • 수신되는 /mcp request에 대해 256KB의 request body 제한이 있습니다(실제 MCP 페이로드는 4KB 미만).
  • 서비스별로 FourA API에 의해 rate limit가 적용됩니다. Rate Limits를 참조하십시오.

셀프 호스팅

전체 서버 소스는 @fouradata/mcp 라이선스 하에 GitHub에 공개되어 있습니다. 저장소를 클론하고, npm install, npm run build을 수행한 후, node dist/http.js을 실행하여 자체 인스턴스를 구축하십시오. 모든 로드 밸런서 뒤에 있는 단일 컨테이너에서 stateless로 실행됩니다.

구성 가능한 환경:

변수 기본값 목적
PORT 3076 HTTP 수신 대기 포트
FOURA_API_BASE https://api.foura.ai/api 업스트림 FourA REST 기본 URL
FOURA_MCP_PAYLOADS_DIR /data/payloads 50KB 이상의 응답이 디스크에 캐시되는 위치 (offload_large: true 사용)
FOURA_MCP_ALLOWED_HOSTS mcp.foura.ai,localhost,127.0.0.1,[::1] Host 헤더에 대한 호스트 이름 허용 목록 (DNS 리바인딩 방어)
FOURA_MCP_ALLOWED_ORIGINS https://mcp.foura.ai,https://claude.ai,https://app.cursor.sh,https://app.cursor.com 브라우저 호출자를 위한 Origin 허용 목록
FOURA_MCP_RESOURCE_METADATA_URL https://foura.ai/docs/mcp/server#auth 401 오류 발생 시 WWW-Authenticate에 반환되는 URL

공식 컨테이너는 uid 1001(루트 아님)으로 실행됩니다. /data/payloads 호스트 바인드 마운트는 해당 UID가 쓸 수 있어야 합니다.

모든 로드 밸런서 뒤에서 수평으로 확장합니다. 클라이언트가 모든 요청에 키를 제공하므로 고정 세션이 없습니다.

최근 업데이트: 2026년 8월 6일
MCP 서버 오류 →