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

MCP 서버

MCP Server

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

GitHub에서 오픈 소스로 제공되며, npm에 @fouradata/mcp로 등록되어 있습니다. 현재 릴리스: 0.7.3.

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

foura.ai/dashboard#api-keys에서 키를 발급받으세요 (원클릭, 생성 시 1회만 표시, 형식 pk_live_...). MCP 클라이언트 설정에 다음 내용을 추가하세요:

{
  "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 확장) .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 설정을 사용하거나 mcp-remote를 통해 호스팅된 엔드포인트를 브리지하십시오:

{
  "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"

401 챌린지에는 의도적으로 RFC 9728 resource_metadata 매개변수가 포함되지 않습니다. 이를 알리면 OAuth 지원 클라이언트가 이 서버에서 구현되지 않은 플로우를 시작하게 됩니다. pk_live_ 키를 Bearer 토큰으로 전송하면 401 오류가 해결됩니다.

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

DNS 리바인딩(CVE-2025-66414) 방지를 위해 서버는 Host 헤더(mcp.foura.ai 또는 localhost여야 함)와 제공된 경우 Origin 헤더(허용 목록: mcp.foura.ai, claude.ai, app.cursor.sh, app.cursor.com)를 검증합니다. 서버 간 호출자(curl, stdio 브리지 모드의 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 key가 필요하지 않습니다.

동일한 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"
  }
}

값은 공백이 제거되고 대문자로 변환되며 중복이 제거됩니다. 출구 위치를 알 수 없는 프록시는 제외되며, 요청되지 않은 국가로 절대 대체되지 않습니다. 선택 시 일반적으로 10분 이내에 업데이트되는 최신 대상 가시 국가 메타데이터를 사용합니다. 요청 중 실시간 위치 조회를 수행하는 것은 아닙니다. 프록시 호스트 주소로부터 서비스 국가를 추론하지 마십시오.

범위 지정이 성공하면 exitCountry 및 재사용 가능한 proxy ID를 반환합니다. exitCountry 항목이 요청된 허용 목록에 속하는지 확인하십시오. 현재 풀에 일치하는 항목이 없으면 도구는 details.exitCountries에 정규화된 범위를 포함하여 code: "no_eligible_proxy"을 반환합니다. 해당 범위를 유지하고 나중에 다시 시도하십시오. 사용자가 요구 사항을 명시적으로 변경할 때만 범위를 변경하거나 넓히십시오. 국가 범위 지정은 Startup 플랜 이상부터 포함됩니다. 해당 기능이 없는 플랜에서 exitCountries을(를) 전송하는 호출은 403 및 X-FourA-Limit: plan_limit_feature와 함께 거부됩니다.

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

아무리 많은 출구를 시도해도 표준 풀이 도달할 수 없는 대상을 위해 exitClass: "premium"을(를) 설정하십시오. 이는 허용일 뿐 지시 사항이 아닙니다. 표준 풀은 여전히 응답을 위해 경합하며 보통 승차하며, 프리미엄 출구를 시도하기 전에 표준 풀이 응답한 요청에는 프리미엄 트래픽 요금이 발생하지 않습니다. 프리미엄 시도는 실패하더라도 전송된 트래픽을 계산합니다. 응답은 exitClass을 premium 또는 standard(으)로 보고하므로, 요청별로 어떤 클래스가 제공되었는지 확인할 수 있습니다. standard은 플랜에 포함된 프리미엄 트래픽이 모두 소진되었을 때의 응답이기도 하며, 오류가 아닌 정상적인 결과입니다. exitClass: "standard"은(는) 상위 단계 전환을 완전히 금지합니다. 프리미엄 출구가 없는 플랜에서 exitClass: "premium"을(를) 사용하면 code: "plan_limit_premium"(으)로 거부됩니다. exitClass 항목을 참조하십시오.

응답을 얻기 위해 로테이션이 다른 브라우저 제품군으로 전환되어야 했던 경우, 성공한 응답에는 최종 결정된 제품군이 포함된 profile이(가) 포함됩니다. 해당 제품군으로 재생성하십시오. 그렇지 않으면 다음 호출에서 실패한 버전이 반복됩니다.

실패한 로테이션에는 오류와 함께 attemptReport이(가) 포함됩니다. 한 줄의 summary 문장과 함께 응답하지 않은 출구(noResponse), 봇 검사에 의해 거부된 출구(defense, vendors의 공급업체 포함), 수신되었으나 자체 validate.data에 의해서만 거부된 페이지(contentRejected), statusRejected 및 other(으)로 구분된 카운트가 제공됩니다. profilesTried은(는) 작업에서 전송된 브라우저를 최초 사용 순서대로 나열하며, default은(는) 요청이 작성된 그대로 전송되었음을 의미합니다. contentRejected 값이 높다는 것은 FourA가 실제 페이지를 제공했으나 자체 규칙에 의해 삭제되었음을 의미합니다. Why a Proxy Request Ran Out of Tries 항목을 참조하십시오.

foura_browser

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

단일 페이지 앱, 지연 로딩 콘텐츠 또는 완료를 위해 실제 브라우저가 필요한 검사가 포함된 페이지에 사용하십시오.

각 도구의 입력 형식, 기본값 및 유효성 검사 규칙은 REST 엔드포인트 참조를 확인하세요. 도구 스키마는 REST API와 필드별로 일치하며, MCP 전용 offload_large 옵트인이 추가됩니다(아래 참조).

대상이 봇 검사를 실행할 때

대상이 본문으로 이동하는 과정에서 봇 검사를 실행한 경우 foura_single 및 foura_proxy는 defense를 반환합니다. defense.solved: true는 검사를 통과하여 data가 실제 페이지임을 의미하며, false는 본문이 챌린지 페이지일 수 있음을 의미합니다. 챌린지 페이지를 콘텐츠로 처리하는 대신 다른 브라우저, os 또는 버전으로 다시 시도하거나 foura_proxy 또는 foura_browser로 업그레이드하세요.

타입이 지정된 응답

모든 도구 응답에는 content(사람이 읽을 수 있는 텍스트 요약)와 structuredContent(도구의 outputSchema에 대해 유효성이 검사된 타입 정의 JSON)가 모두 포함됩니다. 각 도구는 고유한 형식을 갖습니다:

  • foura_auto: 단일 형태의 { status, headers, data } 및 meta({ rung, solved, attempts, credits }, 항상 존재하며 rung는 cache, probe, proxy, browser, warmup, fail 중 하나임)와 하위 수준 도구를 통한 재생을 위한 기본값 session({ proxy, cookies, userAgent }). total_time 없음.
  • foura_single: { status, headers, data, total_time, ... } (headers는 배열이며 리디렉션 홉당 하나의 항목이 포함됨)
  • foura_proxy: single과 동일하지만 { proxy, total }가 추가됨. 범위가 지정된 성공에는 exitCountry도 포함되고, 클래스를 지정한 요청에는 exitClass가 포함되며, 브라우저 계열을 변경한 로테이션에는 profile가 포함되고, 실패에는 attemptReport가 포함됨
  • foura_browser: 고유 형태 { status, headers: object, body, cookies, userAgent } (참고: body는 content-type에 따라 문자열 또는 객체일 수 있음)

모든 도구는 API의 응답 헤더에서 읽은 호출 비용 및 추적 방법도 보고합니다:

  • credits - 이 호출에 사용된 크레딧입니다. 작업은 어느 쪽이든 수행되었으므로 실패 시에도 표시됩니다. 성공한 호출에 대해서만 요금이 청구되므로 실패 시 여기에 크레딧이 표시되지만 비용은 청구되지 않습니다.
  • request_id - FourA의 호출 ID입니다. 지원 요청 시 이 값을 인용하세요.
  • exitClass - 프리미엄 출구가 호출을 처리한 경우의 premium입니다. foura_single 및 foura_browser에서는 proxy가 foura_proxy가 찾은 출구를 재생할 때 발생합니다.

API가 아무것도 보고하지 않은 경우 각 항목은 생략되므로 이전 버전을 기반으로 작성된 클라이언트는 변경 없이 계속 작동합니다. 동일한 값이 응답 헤더에 설명되어 있습니다.

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

다중 값 응답 헤더

여러 번 나타나는 헤더(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에 세션, 트래킹, 동의 cookie를 함께 설정하는 사이트(대부분의 전자상거래 사이트)에서 중요합니다.

대용량 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를 가져옵니다. 호스팅 서버에서 캐시된 페이로드는 1시간 후에 만료됩니다. 자체 인스턴스에서는 저장된 페이로드가 자동으로 삭제되지 않으므로, 1시간이 지난 파일을 페이로드 디렉터리에서 직접 정리하십시오.

{
  "method": "GET",
  "url": "https://en.wikipedia.org/wiki/Web_scraping",
  "offload_large": true
}
Client offload_large: true
Claude Desktop 미지원, 기본값 false 유지
Claude Code, Cursor, Windsurf 지원됨
VS Code MCP extension 지원됨

테넌트 격리: 각 API key는 고유한 네임스페이스(sha256(apiKey)[:16])를 가집니다. 페이로드를 저장한 키만 해당 데이터를 다시 읽을 수 있습니다. 테넌트 간 읽기 시도는 존재 여부 유출 없이 Payload not found을 반환합니다.

Built-in Prompts

모든 MCP 클라이언트의 /prompts 아래에 6가지 워크플로 템플릿이 제공됩니다. 각 템플릿은 이름이 지정된 인수를 받아 하나 이상의 도구를 조율하는 템플릿 기반 사용자 메시지를 반환합니다.

Prompt Arguments 동작
smart_fetch url, 선택적 must_contain, extract 자동 fetch(메서드 선택, 봇 보호 처리) 후 콘텐츠 반환 또는 추출
scrape_product_page url 브라우저 fetch 후 제품명, 가격, 이미지, 재고, SKU를 JSON으로 추출
extract_article url proxy fallback을 포함한 single 요청 후 내비게이션/광고를 제거하고 정제된 기사 JSON 반환
monitor_pricing url, 선택적 target_price proxy fetch, 현재 가격 추출, 목표 가격과 비교
check_endpoint_health url, 선택적 expected_text 엄격한 유효성 검사를 포함한 single 요청, 도달 가능성 및 타이밍 반환
bulk_fetch_urls urls(쉼표로 구분) 병렬 single 요청, URL별 proxy 자동 fallback, 메타데이터만 반환

프롬프트는 유휴 상태에서 토큰을 전혀 소모하지 않습니다. 호출된 프롬프트만 LLM 컨텍스트에 포함됩니다.

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

Error envelope

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

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

HTTP 상태 코드가 있는 업스트림 오류의 경우 status도 제공됩니다. 속도 제한 및 용량 오류 시 업스트림 엔벨로프에 retryAfter, current.{concurrency, rpm} 및 limits.{maxConcurrency, maxRpm}이 추가됩니다. 기본 REST 형태는 API Errors를 참고하십시오.

안정된 code 값:

Code HTTP 의미 재시도 안전 여부
ssrf_blocked n/a 대상이 비공개 또는 예약된 주소(RFC 5735, 6598, IPv6 예약됨)이거나, URL이 http(s)가 아니거나, 호스트 이름이 확인되지 않음 불가능. URL을 확인하십시오. 일시적으로 실패한 조회는 재시도할 수 있습니다
upstream_non_json 다양함 업스트림에서 잘못된 형식의 본문을 반환함 불확실. 원인을 확인하십시오
output_validation_failed n/a MCP 서버의 outputSchema이(가) 업스트림 응답을 거부했거나 도구가 호출을 완료하지 못함 (API 키가 구성되지 않았거나 API에 연결할 수 없음) 불확실. 설정을 확인한 후 보고하십시오
bad_request 400 입력 형태가 거부됨 불가능. 인수를 수정하십시오
auth_failed 401 키가 누락되었거나 유효하지 않거나 비활성화됨 불가능. 키를 수정하십시오
forbidden 403 대상이 403으로 응답했고 validate이(가) 이를 거부함 (사이트 검사, 국가 제한) 불가능 또는 foura_proxy(으)로 전환
not_found 404 대상 또는 엔드포인트가 없음 불가능
rate_limited 429 RPM 한도 도달 가능. retryAfter 대기
at_capacity 503 동시성 한도 도달 가능. retryAfter 대기
service_disabled 503 유지보수를 위해 서비스가 꺼져 있습니다. 요금제에 포함되지 않은 도구는 plan_limit_feature(으)로 반환됩니다 지원팀에 문의
service_unavailable 503 일반 503 가능. 짧은 백오프 적용
upstream_error 500+ 또는 0 대상이 서버 오류로 응답했거나, foura_proxy 환경에서 foura_browser 및 foura_auto이(가) 응답하지 않음 가능. 지수 백오프 적용
upstream_client_error 4xx 기타 4xx 일반적으로 불가능
upstream_unknown 기타 요청이 실행되었으나 승인된 응답이 생성되지 않음: foura_single에서는 대상이 응답하지 않았으며(타임아웃, 연결 거부), 모든 도구에서 validate이(가) 2xx 또는 3xx 응답을 거부했습니다. status 및 error을 확인하십시오 조사 필요
no_eligible_proxy n/a 엄격한 exitCountries 범위와 일치하는 프록시가 없음 나중에 재시도. 명시적으로만 범위를 변경하십시오
plan_limit_* 403 또는 429 요금제 한도 중 하나로 인해 호출이 거부됨: plan_limit_ 뒤에 feature, premium, concurrency, rate, browser_daily, credits 또는 bandwidth. MCP Server Errors를 참조하십시오 retryAfter이(가) 있는 경우 대기. 그렇지 않으면 한도가 재설정되거나 요금제가 변경될 때까지 대기

LLM 에이전트는 줄글을 파싱하지 않고 code을(를) 직접 읽어 재시도 로직을 처리할 수 있습니다. 인증 안내: Authentication.

Limits

  • 기본적으로 인라인 본문을 사용합니다. offload_large: true 적용 시 50 KB 이상의 응답은 디스크 + resource_link(테넌트별, 1시간 TTL)로 전달됩니다.
  • 사설 대상(RFC 5735, RFC 6598, IPv6 예약 블록)은 MCP 계층에서 거부됩니다. 공용 호스트만 전달됩니다.
  • 인바운드 /mcp 요청의 본문 크기는 최대 256 KB로 제한됩니다 (실제 MCP 페이로드는 4 KB 미만).
  • Rate limit은 FourA API에서 서비스별로 적용됩니다. Rate Limits를 참고하세요.

Self-Hosting

전체 서버 소스는 @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 시스템 임시 디렉터리 내 foura-mcp-payloads 폴더 (제공된 Docker Compose 파일은 /data/payloads로 설정) 50 KB 이상 응답이 디스크에 캐시되는 경로 (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 허용 목록

공식 컨테이너는 uid 1001(비루트) 사용자로 실행됩니다. /data/payloads 호스트 바인드 마운트는 해당 UID로 쓰기 가능해야 합니다.

임의의 로드 밸런서 뒤에서 수평 확장이 가능합니다. 클라이언트가 모든 요청마다 키를 제공하므로 고정 세션(sticky session)이 필요하지 않습니다.

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