MCP

Foca MCP를 사용하면 AI 클라이언트에서 크레딧 잔액을 확인하고, HTTPS 이미지 URL로 확대 작업을 만들고, 결과를 가져올 수 있습니다. 고급 확대 엔진 physics를 사용하며 웹사이트 계정의 크레딧과 요금제 권한을 공유합니다. 작업 하나당 이미지 한 장을 처리합니다. 기본 출력은 2K이며 이미지당 15크레딧이 필요합니다.

클라이언트 연결

MCP 작업과 새 API 키를 만들려면 유효한 유료 구독 또는 크레딧 팩 구매 이력이 필요합니다. 크레딧 팩 구매에 성공했다면 잔액이 0이 되어도 자격이 유지됩니다. 가입 선물 크레딧은 자격을 제공하지 않습니다. 크레딧 팩만 구매한 계정은 2K 작업을 만들 수 있으며 더 높은 해상도에는 해당하는 유효 구독이 필요합니다.

1. 로그인 후 API 키 설정에서 키를 만드세요.
2. 키가 표시되면 바로 저장하세요. 전체 키는 한 번만 표시됩니다.
3. 아래에서 클라이언트를 선택하세요. 엔드포인트는 Streamable HTTP와 Authorization: Bearer YOUR_API_KEY를 사용합니다.

{
  "mcpServers": {
    "foca": {
      "url": "https://focaupscaler.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "foca-api-key",
      "description": "Foca API key",
      "password": true
    }
  ],
  "servers": {
    "foca": {
      "type": "http",
      "url": "https://focaupscaler.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:foca-api-key}"
      }
    }
  }
}

claude mcp add --transport http foca https://focaupscaler.com/api/mcp   --header 'Authorization: Bearer YOUR_API_KEY'

[mcp_servers.foca]
url = "https://focaupscaler.com/api/mcp"
bearer_token_env_var = "FOCA_API_KEY"

export FOCA_API_KEY='YOUR_API_KEY'

{
  "mcpServers": {
    "foca": {
      "serverUrl": "https://focaupscaler.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "foca": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.15.1",
        "https://focaupscaler.com/api/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${FOCA_AUTH_HEADER}"
      ],
      "env": {
        "FOCA_AUTH_HEADER": "Bearer YOUR_API_KEY"
      }
    }
  }
}

API 키는 계정 권한으로 작동하며 계정 크레딧을 사용할 수 있습니다. 클라이언트의 비밀 설정에 보관하고 사용하지 않는 키는 API 키 설정에서 폐기하세요. URL, 프롬프트 또는 코드 저장소에 키를 넣지 마세요. 작업과 크레딧은 키를 만든 계정에 귀속됩니다.

“ChatGPT에서 읽기”와 “Claude에서 읽기”는 이 공개 가이드를 읽는 프롬프트를 엽니다. MCP를 연결하거나 계정 접근을 허용하지 않습니다.

크레딧과 요금제 권한

작업 제출 전에 get_upscale_info를 호출하세요. 각 단계의 available은 요금제 이용 권한을 나타내며, balance도 작업 비용 이상이어야 합니다. MCP와 웹사이트는 같은 크레딧 잔액을 사용합니다. 요금제 및 크레딧에서 요금제를 변경하거나 크레딧을 추가할 수 있습니다.

이미지 입력 조건

• 추가 인증 없이 다운로드할 수 있는 443 포트의 공개 HTTPS URL이어야 합니다. URL에 사용자 이름이나 비밀번호를 포함할 수 없으며 사설 네트워크와 로컬 주소는 거부됩니다.
• 유효한 JPEG, PNG 또는 WebP 파일이어야 하며 최대 20MB, 즉 20MiB 또는 20,971,520바이트까지 지원합니다.
• 입력 이미지는 최대 6,400만 픽셀(64MP)까지 지원합니다.
• 임시 서명 URL은 다운로드가 끝날 때까지 유효하면 사용할 수 있습니다. 다운로드 제한 시간은 20초이며 리디렉션은 최대 세 번 허용됩니다.

이미지 다운로드나 검증에 실패하면 작업이 생성되지 않으며 작업 크레딧도 차감되지 않습니다.

JSON-RPC 요청 예시

MCP 클라이언트는 일반적으로 초기화와 도구 검색을 자동으로 처리합니다. 요청을 직접 확인하려면 같은 터미널 세션에서 다음 예시를 실행하세요. API 키와 예시 이미지 URL을 실제 값으로 바꾸세요.

모든 요청은 POST와 아래 헤더를 사용합니다. 엔드포인트는 JSON을 반환하며 상태를 유지하지 않습니다. 세션 ID를 발급하지 않고 별도의 GET SSE 연결도 제공하지 않습니다. 예시는 프로토콜 버전 2025-11-25를 사용합니다. 클라이언트는 이후 요청에서 initialize로 협상한 버전을 사용해야 합니다.

export FOCA_API_KEY='YOUR_API_KEY'

foca_mcp() {
  curl --silent --show-error 'https://focaupscaler.com/api/mcp' \
    --header "Authorization: Bearer $FOCA_API_KEY" \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json, text/event-stream' \
    --header 'MCP-Protocol-Version: 2025-11-25' \
    --data-binary @-
}

초기화와 도구 검색

initialize를 보내고 초기화가 성공하면 notifications/initialized 알림을 보내세요. 초기화 결과에는 서버 이름 foca-upscaler와 도구 지원 기능이 포함됩니다.

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "foca-example-client",
      "version": "1.0.0"
    }
  }
}
JSON

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}
JSON

tools/list로 도구 스키마를 조회하세요.

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
JSON

응답의 result.tools에는 get_upscale_info, upscale_image, get_upscale_task가 포함됩니다. 각 도구의 inputSchema를 따르세요. 추가 인수는 거부됩니다.

1. get_upscale_info로 계정 확인

인수는 빈 객체 {}입니다. 이 조회는 작업 크레딧을 사용하지 않습니다.

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_upscale_info",
    "arguments": {}
  }
}
JSON

모든 해상도를 이용할 수 있는 계정의 result.structuredContent 예시입니다.

{
  "engine": "physics",
  "balance": 200,
  "can_create_tasks": true,
  "tiers": [
    { "resolution_tier": 2, "credits": 15, "available": true },
    { "resolution_tier": 4, "credits": 30, "available": true },
    { "resolution_tier": 8, "credits": 60, "available": true },
    { "resolution_tier": 16, "credits": 120, "available": true }
  ],
  "max_file_size_bytes": 20971520,
  "formats": ["image/jpeg", "image/png", "image/webp"]
}

balance는 현재 크레딧 잔액입니다. tiers는 단계별 비용과 요금제 이용 권한을 나타냅니다. max_file_size_bytes와 formats는 지원하는 파일 크기와 형식입니다. 도구 응답의 content 텍스트 항목에도 같은 데이터가 JSON 문자열로 포함됩니다. 예시에는 해석된 structuredContent만 표시합니다.

can_create_tasks는 현재 계정의 MCP 유료 이용 자격을 나타냅니다. 구독이 만료되어도 유효하고 폐기되지 않은 API 키는 get_upscale_info와 get_upscale_task를 호출할 수 있습니다. 크레딧 팩 구매 성공 이력이 없다면 can_create_tasks가 false가 되어 새 작업을 만들 수 없습니다. 이 필드가 잔액 충족이나 모든 해상도 접근을 보장하지는 않습니다.

2. upscale_image로 작업 생성

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "upscale_image",
    "arguments": {
      "image_url": "https://images.example.com/source.png",
      "resolution_tier": 2,
      "idempotency_key": "source-001-2k"
    }
  }
}
JSON

새 작업은 처리가 끝나기 전에 다음과 같은 result.structuredContent를 반환할 수 있습니다.

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "status": "pending",
  "credits_charged": 15,
  "credits_remaining": 185,
  "resolution_tier": 2
}

이후 조회에는 task_id의 UUID를 사용하세요. 작업은 비동기로 처리되므로 생성 응답을 받을 때 status가 이미 다음 단계로 바뀌었을 수도 있습니다. credits_charged는 작업의 크레딧 비용을 기록합니다. 현재 잔액은 get_upscale_info를 다시 호출해 확인하세요.

작업 생성과 조회 모두 credits_remaining으로 응답 시점의 현재 계정 잔액을 반환합니다. 멱등성 재요청은 현재 잔액을 반환하므로 처음 차감 직후의 잔액과 다를 수 있습니다.

3. get_upscale_task로 결과 조회

유일한 인수는 필수 값인 task_id이며 작업 생성 시 반환된 UUID를 사용합니다. API 키가 속한 계정의 작업만 조회할 수 있습니다. 아래 예시 UUID를 실제 작업 ID로 바꾸세요.

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_upscale_task",
    "arguments": {
      "task_id": "00000000-0000-4000-8000-000000000001"
    }
  }
}
JSON

완료된 작업은 다음 형식의 result.structuredContent를 반환합니다. URL과 시간은 예시입니다.

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "status": "succeeded",
  "credits_charged": 15,
  "credits_remaining": 185,
  "resolution_tier": 2,
  "download_url": "https://downloads.example.com/result.png?signature=EXAMPLE",
  "expires_at": "2026-10-17T13:00:00.000Z"
}

작업 상태와 결과 유효기간

get_upscale_task 호출 사이에 간격을 두고 요청 제한이 발생하면 대기 시간을 늘리세요. 상태가 succeeded, failed가 되면 조회를 중지하세요. 작업은 서버에서 계속 진행되므로 처리 중 MCP 연결을 유지할 필요는 없습니다.

다운로드 링크는 임시로 유효합니다. expires_at은 ISO 8601 타임스탬프이며 실제 반환된 시간을 기준으로 사용하세요. 링크의 기본 유효기간은 한 시간이지만 서비스 설정에 따라 달라질 수 있습니다. 링크만 만료되었다면 결과 보관 기간 안에 작업을 다시 조회해 새 서명 링크를 받을 수 있습니다.

작업 결과는 작업 생성 시점부터 24시간 동안 보관됩니다. 이후 조회하면 status: "failed"와 error_code: "RESULT_EXPIRED"가 반환되며 기록이 삭제되었다면 TASK_NOT_FOUND가 반환됩니다. 보관 기간 안에 다운로드하여 직접 저장하세요.

재시도와 멱등성

요청 시간이 초과되거나 응답을 잃어버린 뒤 재시도할 때는 idempotency_key, image_url, resolution_tier를 모두 동일하게 유지하세요. 반복 요청은 기존 작업을 반환하며 작업 크레딧을 다시 차감하지 않습니다. 멱등성 키의 범위는 계정이며 같은 계정의 다른 API 키로 보낸 요청에도 적용됩니다.

다른 이미지 URL이나 해상도에는 새 키를 사용하세요. 같은 키에 다른 인수를 보내면 IDEMPOTENCY_CONFLICT가 발생합니다. 응답을 받지 못했다는 이유만으로 새 키를 만들지 마세요. 원래 작업이 이미 생성되었을 수 있습니다. 서명 URL의 쿼리 문자열을 바꾸는 것도 요청 인수 변경에 해당합니다.

멱등성 기록은 최소 30일 동안 보관되며, 30일이 지나면 일일 정리로 삭제됩니다. 삭제 후 이전 키를 다시 사용하면 새 작업이 생성되고 크레딧이 차감될 수 있습니다. 이 기간이 지난 생성 요청은 재시도하지 마세요. 작업 결과의 별도 보관 기간은 계속 24시간입니다.

오류와 요청 제한

비즈니스 도구 실행에 실패하면 result.isError가 true가 되고 result.structuredContent.error.code와 message가 반환됩니다. 메시지 문구 대신 오류 코드를 기준으로 처리하세요. 잘못된 JSON-RPC 요청이나 스키마에 맞지 않는 인수는 프로토콜 계층에서 거부됩니다.

클라이언트 언어와 관계없이 오류 메시지는 영어로 반환됩니다. 잔액이 부족하면 result.structuredContent에 아래 오류 상세가 포함됩니다. required_credits와 credits_remaining으로 부족한 크레딧을 안내하고 upgrade_url로 요금 페이지를 여세요.

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits to create this task.",
    "required_credits": 15,
    "credits_remaining": 5,
    "upgrade_url": "https://focaupscaler.com/pricing"
  }
}

계정당 분당 MCP 요청 60회와 분당 새 작업 제출 시도 5회까지 허용됩니다. HTTP 계층은 키가 없거나 유효하지 않거나 폐기된 경우 401 UNAUTHORIZED, Origin 헤더가 거부된 경우 403 INVALID_ORIGIN, 요청이 제한된 경우 429 RATE_LIMITED와 Retry-After: 60, 서비스 이용이 불가능한 경우 503 MCP_UNAVAILABLE을 반환할 수 있습니다. 필요한 인증 헤더를 전송할 수 있는 원격 MCP 클라이언트를 사용하세요.

API 키 설정에서 유료 자격이 없는 계정의 POST /api/mcp/keys 요청은 HTTP 403 PAID_ACCESS_REQUIRED를 반환하며 키 생성이 일시적으로 불가능하면 HTTP 503 MCP_UNAVAILABLE를 반환합니다. 기존 키 조회와 폐기는 계속 사용할 수 있습니다. 유효하지 않은 MCP Bearer 키는 항상 HTTP 401을 반환하며 성공한 도구 응답으로 처리되지 않습니다.

연결 테스트

연결한 뒤 클라이언트에 다음 프롬프트를 보내세요.

Foca의 get_upscale_info를 호출하여 남은 크레딧과 사용 가능한 출력 해상도를 보여 주세요. 이미지 작업은 생성하지 마세요.

정상 응답은 도구 검색과 인증이 성공했음을 나타냅니다. 이 읽기 전용 확인은 작업 크레딧을 사용하지 않습니다. 이후 이미지 처리를 테스트하려면 본인의 공개 HTTPS 이미지 URL과 출력 해상도를 명시하세요. 작업을 생성하면 위에 표시된 크레딧이 차감됩니다.

개인정보 및 약관

이미지를 제출하기 전에 개인정보 처리방침과 서비스 약관을 확인하세요. 처리 권한이 있는 이미지만 제출하세요.