MCP Server

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

Quick Start: local stdio (Claude Desktop 권장)

foura.ai/dashboard#api-keys에서 키를 발급받으세요 (클릭 한 번으로 생성되며 생성 시 한 번만 표시됩니다. 형식: 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를 다운로드하고(약 10초 소요) 이를 MCP 클라이언트의 하위 프로세스로 실행합니다. 전역 설치는 필요하지 않습니다.

Client	설정 파일 위치
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_single, foura_proxy, foura_browser)와 5개의 프롬프트가 도구 목록에 나타납니다.

Quick Start: hosted (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 빌드는 순수 url 형식을 거부합니다. Claude Desktop의 경우 위의 stdio 설정을 사용하거나 mcp-remote를 통해 브릿지하세요:

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

Hosted endpoint reference

속성	값
URL	`https://mcp.foura.ai/mcp`
Transport	Streamable HTTP (POST `/mcp`, SSE responses)
Authentication	request당 `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 challenge	`WWW-Authenticate: Bearer realm="foura-mcp", resource_metadata="https://foura.ai/docs/mcp/server#auth"`

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

DNS-rebinding(CVE-2025-66414) 보호를 위해, 서버는 Host header(mcp.foura.ai 또는 localhost여야 함) 및 존재하는 경우 Origin header(허용 목록: mcp.foura.ai, claude.ai, app.cursor.sh, app.cursor.com)를 검증합니다. 서버 간 호출자(curl, stdio 브릿지 모드의 MCP 클라이언트)는 Origin을 전송하지 않으며 그대로 통과합니다.

Tools

MCP 2025-06-18 사양에 따라 세 가지 도구 모두 readOnlyHint: true 및 openWorldHint: true로 주석이 지정되어 있습니다. 신뢰할 수 있는 읽기 전용 도구를 자동 승인하는 클라이언트는 request별 확인 모달 없이 도구를 호출합니다.

foura_single

단일 HTTP request를 보내고 response를 받습니다. 200ms에서 2s 정도 소요됩니다. POST /api/single/을 1대1로 미러링합니다.

정적 페이지, JSON API, 서버 렌더링 HTML에 사용하세요.

foura_proxy

자동 재시도를 지원하는 순환 proxy 풀을 통해 HTTP request를 라우팅합니다. 1s에서 5s 정도 소요됩니다. POST /api/proxy/를 미러링합니다.

foura_single이 403, CAPTCHA 또는 지역 차단된 콘텐츠를 반환할 때 사용하세요. response에는 성공한 proxy ID(proxy)와 초 단위의 외부 실제 소요 시간(total, float)이 포함됩니다.

foura_browser

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

싱글 페이지 앱, 지연 로딩(lazy-loaded) 콘텐츠 또는 차단을 해제하기 위해 실제 브라우저가 필요한 안티봇 챌린지 뒤에 있는 페이지에 사용하세요.

각 도구의 입력 형태, 기본값 및 검증 규칙은 REST endpoint reference를 참조하세요. 도구 스키마는 REST API와 필드 대 필드로 일치하며, MCP 전용 offload_large 옵트인(아래 참조)이 추가됩니다.

Typed responses

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

foura_single: { status, headers, data, total_time, ... } (headers는 배열이며, 리다이렉트 홉당 하나의 항목이 포함됨)
foura_proxy: single과 동일하며 { proxy, total }이 추가됨 (여기서 total은 재시도를 포함한 외부 타이밍의 초 단위 float 값)
foura_browser: 별도의 형태 { status, headers: object, body, cookies, userAgent } (참고: body는 content-type에 따라 문자열 또는 객체일 수 있음)

structuredContent를 지원하는 클라이언트(2026년 기준 Claude Desktop, Cursor, Windsurf)는 타입이 지정된 객체를 LLM에 직접 전달하여 문자열 형태의 JSON 재토큰화 과정을 건너뜁니다. 일반적인 response에서 30-40%의 토큰 절감 효과를 기대할 수 있습니다.

Multi-value response headers

여러 번 나타나는 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에서 세션, 추적, 동의 cookie를 동시에 설정하는 사이트(대부분의 이커머스)에서 중요합니다.

Large responses: `offload_large` (기본값: inline)

기본적으로(v0.2.0부터) 전체 response body는 크기에 관계없이 structuredContent 내에 인라인으로 반환됩니다. 이는 모든 MCP 클라이언트에서 기본적으로 작동합니다.

클라이언트가 MCP resources/read를 지원하고 대용량 페이지에서 토큰을 절약하려는 경우, 도구 호출 시 offload_large: true를 전달하세요. 그러면 50 KB 이상의 response는 디스크에 기록되고 resource_link로 반환되며, 클라이언트는 실제로 필요할 때만 body를 가져옵니다. 캐시된 페이로드는 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	지원됨

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

Built-in Prompts

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

Prompt	Arguments	기능
`scrape_product_page`	`url`	브라우저로 가져온 후 상품명, 가격, 이미지, 재고, SKU를 JSON으로 추출
`extract_article`	`url`	proxy fallback이 포함된 single을 실행한 후, 탐색/광고를 제거하고 깔끔한 기사 JSON을 반환
`monitor_pricing`	`url`, 선택 사항 `target_price`	proxy로 가져온 후 현재 가격을 추출하여 목표 가격과 비교
`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": "single | proxy | browser",
  "code": "rate_limited",
  "error": "Rate limit exceeded"
}

HTTP status가 있는 업스트림 에러의 경우 status도 존재합니다. rate limit 및 용량 에러의 경우, 업스트림 봉투에 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	업스트림이 잘못된 형식의 body를 반환함	아마도 가능, 조사 필요
`output_validation_failed`	n/a	MCP 서버의 `outputSchema`가 업스트림 response를 거부함 (서버 버그 또는 예상치 못한 업스트림 형태)	아마도 가능, 보고 필요
`bad_request`	400	입력 형태가 거부됨	아니요, 인수를 수정하세요
`auth_failed`	401	키가 누락되었거나, 유효하지 않거나, 비활성화됨	아니요, 키를 수정하세요
`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+	업스트림 5xx 에러	예, 지수 백오프 후 재시도
`upstream_client_error`	4xx	기타 4xx 에러	일반적으로 아니요
`upstream_unknown`	other	방어적 코드, 실제로는 발생하지 않아야 함	조사 필요

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

Limits

기본적으로 인라인 body를 사용합니다. offload_large: true 설정 시, 50 KB 이상의 response는 디스크에 저장되고 resource_link로 반환됩니다 (테넌트별, 1시간 TTL).
사설 대상은 MCP 레이어에서 거부됩니다 (RFC 5735, RFC 6598, IPv6 예약 블록). 공인 호스트만 전달됩니다.
수신되는 /mcp request의 request body 한도는 256 KB입니다 (실제 MCP 페이로드는 4 KB 미만).
rate limit는 서비스별로 FourA API에 의해 강제 적용됩니다. Rate Limits를 참조하세요.

Self-Hosting

각 인스턴스는 하나의 컨테이너에서 stateless하게 실행됩니다. 공개 GitHub 미러는 v1.0과 함께 출시될 예정입니다. 그 전까지 소스는 비공개 리포지토리에 있으며 컨테이너 이미지는 요청 시 제공됩니다. 조기 액세스를 원하시면 support@foura.ai로 문의하세요.

구성 가능한 환경 변수:

변수	기본값	용도
`PORT`	`3076`	HTTP 수신 대기 포트
`FOURA_API_BASE`	`https://api.foura.ai/api`	업스트림 FourA REST 기본 URL
`FOURA_MCP_PAYLOADS_DIR`	`/data/payloads`	50 KB 이상의 response가 디스크에 캐시되는 위치 (`offload_large: true` 설정 시)
`FOURA_MCP_ALLOWED_HOSTS`	`mcp.foura.ai,localhost,127.0.0.1,[::1]`	`Host` header에 대한 호스트 이름 허용 목록 (DNS-rebinding 방어)
`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(non-root)로 실행됩니다. /data/payloads 호스트 바인드 마운트는 해당 uid가 쓰기 가능해야 합니다.

모든 로드 밸런서 뒤에서 수평적으로 확장할 수 있습니다. 클라이언트가 모든 request마다 키를 제공하므로 sticky session이 필요하지 않습니다.

최근 업데이트: 2026년 7월 1일

MCP Server

MCP Server

Quick Start: local stdio (Claude Desktop 권장)

Quick Start: hosted (Streamable HTTP)

Hosted endpoint reference

Tools

foura_single

foura_proxy

foura_browser

Typed responses

Multi-value response headers

Large responses: offload_large (기본값: inline)

Built-in Prompts

Error envelope

Limits

Self-Hosting

Large responses: `offload_large` (기본값: inline)