MCP 도구 레퍼런스
이 페이지는 OAuth 원격 MCP 1.12.1 릴리스의 도구 16개를 설명합니다. 연결된 서버의tools/list가 기준입니다. 로컬 stdio는 prepare_upload와 get_upload를 제공하지 않으며, 로컬 stdio의 upload_file은 명시적으로 허용된 디렉토리 안의 경로도 받습니다.
name과 arguments로 된 예시는 MCP 도구 호출을 나타내며, REST 요청 본문이 아닙니다. 예시가 있다고 해서 유료 생성이 승인되는 것은 아닙니다.
search_models
recommend_models
search_docs
get_model
필수model: 1–128자의 문자열이며, 반환된 정식 ID 또는 지원되는 별칭을 사용합니다.
estimate_cost
pricing_quote도 없습니다. total_known은 false이고, missing_usage에는 빠진 값이 하나씩 나열되며, usage_help는 그 값을 제공하는 방법을 알려 줍니다. 과금을 참고하세요. 조회가 성공했다고 해서 입력이 유효하다거나 견적이 완전하다는 뜻은 아닙니다.
승인할 수 있는 예상 비용은 pricing_quote도 함께 반환합니다. 이는 정확히 이 입력에 대한 승인 기록입니다. 사용자가 승인하면 같은 입력과 함께 생성 도구에 전달하세요. 이 기록은 예상 비용을 산정한 시점부터 24시간 동안(expires_at), 승인된 가격 이하일 때 유효합니다. 생성 도구는 예상 비용을 다시 산정하고 가격이 그대로이거나 더 낮으면 제출하며, 이후에 가격 규칙이 바뀐 경우에도 마찬가지입니다. 가격이 올랐으면 price_changed, 입력이 바뀌었으면 quote_input_changed, pricing_quote가 만료되었으면 quote_expired로 거부되며, 각각 예상 비용을 새로 산정하고 다시 승인받아야 합니다. inputs를 사용하면 결과에 입력별 예상 비용과 합계가 나열되고, pricing_quote 하나가 정확히 그 입력들을 그 순서대로 승인합니다. 이 배치용 승인 기록으로는 단일 입력을 승인할 수 없으며, 단일 입력의 pricing_quote로 배치를 승인할 수도 없습니다.
이 도구에는 max_cost_usd 인수가 없으며, CLI의 로컬 quote_id를 만들지도 않습니다. MCP의 예산 검사는 생성 도구에서 이루어집니다. media_seconds는 출력 길이를 설정하지 않으며, 알 수 없는 참조 영상 배율을 채워 주지도 않습니다.
get_pricing_rules
estimate_cost를 사용하세요. 결과가 비어 있다면 일치하는 공개 규칙이 없다는 뜻이지, 모델이 무료라는 뜻이 아닙니다. 목록 조회에서는 규칙을 읽을 수 없거나 규칙이 불완전한 모델이 제외되어 rejected_models에 나열되고 warnings에 표시됩니다. 다른 모델은 평소대로 반환되며, 제외된 모델이 무료인 것은 아닙니다. 단일 모델 조회는 규칙을 읽을 수 없으면 여전히 실패합니다.
generate_image, generate_video, generate_audio
출력 유형에 맞는 도구를 선택하세요. 이 도구들은 다음 최상위 인수를 공유합니다:
호출하기 전에 모델과 입력을 확인하고, 요청 전체의 예상 비용을 산정하고, 제한 사항을 알리고, 비용에 대한 명시적인 승인을 받으세요. 단, 사용자가 예상 비용 산정을 생략하기로 한 경우(아래 참고)는 예외입니다. 아래는 호출 형식을 보여 주는 예시입니다:
wait_seconds로 세 도구 각각의 대기 시간을 바꿀 수 있습니다. 제출 시 선차감 금액이 보고될 수 있는데, 이는 완료된 작업의 비용과 구분해야 합니다.
진행 상황을 확인하려고 생성을 다시 호출하지 말고, 실행 중인 작업을 조회하세요. 응답을 받지 못했다면 원래 ID, 계정, 입력, 요청 ID를 그대로 유지하세요. 요청 ID가 달라지면 새로운 유료 요청이 만들어집니다. 클라이언트의 복구 보호 장치가 있다고 해서 모든 프로덕션 노드에서 백엔드 멱등성이 동일하게 보장된다는 증거는 아닙니다.
예상 비용 산정 없이 생성하기. 사용자가 예상 비용 산정이나 확인을 하지 말라고 명시적으로 말하면(예: “바로 생성해 주세요” 또는 “이제부터는 그냥 생성해 주세요”), 어시스턴트는 사용자가 정한 범위 안에서 estimate_cost와 확인 절차를 건너뛰고 skip_estimate: true를 전달합니다. 범위는 이번 작업, 이번 배치, 또는 대화의 남은 부분입니다. 어시스턴트는 사용자의 침묵, 잔액, 자신의 제안을 근거로 이를 추론해서는 안 됩니다. 사용자가 대화의 남은 부분 전체에 대해 생략하기로 하면, 어시스턴트는 이후 생성은 묻지 않고 제출된다는 점을 한 번 알립니다. 새 대화를 시작하거나 예상 비용 산정을 다시 해 달라고 요청하면 원래대로 돌아갑니다. 예상 비용 산정을 생략한 생성은 가격을 계산할 수 없거나 pricing_quote가 만료, 가격 인상, 입력 변경을 이유로 거부되더라도 제출되며, 결과에 그 사실이 표시됩니다(estimate_skipped, estimate_skip_reason). 작업 요금은 실제 사용량에 따라 부과됩니다. 유효하지 않은 입력은 여전히 거부되고, 명시적인 max_cost_usd도 그대로 적용되며(이 값을 넘는 요청이나, 가격을 이 값과 대조해 확인할 수 없는 요청은 제출되지 않습니다), 모델의 웹 검색이나 이미지 검색을 켜려면 여전히 사용자의 승인이 필요합니다. 예상 비용 산정이 실패했거나 합계가 없는데 사용자가 생략을 선택하지 않은 경우, 어시스턴트는 실제 사용량 기준 요금으로 그래도 생성할지 한 번 묻습니다.
배치. 한 모델로 여러 작업을 만들 때는 inputs(1–50개 항목, 각각 input과 같은 형식)를 estimate_cost에 전달한 다음, 반환된 pricing_quote와 함께 생성 도구에 전달하세요. 예상 비용 산정 한 번, 합계에 대한 승인 한 번, 그리고 호출 한 번으로 모든 항목을 제출하며(동시에 최대 10개씩), 기다리지 않고 항목별 task_id 또는 오류를 반환합니다. 유효하지 않은 항목이 하나라도 있으면 아무것도 제출되지 않습니다. max_cost_usd는 배치 합계에 적용되고, media_seconds와 pricing_parameters는 모든 항목에 적용됩니다. 결과는 list_tasks(task_ids, 호출당 최대 50개)로 수집하세요. 서로 다른 모델의 작업은 wait_seconds: 0을 지정해 호출 한 번에 하나씩 제출하세요. 이미지 수를 n에 의존하지 마세요. GPT Image 같은 일부 모델은 n보다 적은 수의 이미지를 반환하는 경우가 많으므로, 이미지 한 장마다 항목을 하나씩 사용하세요.
호출이 시작된 지 25초가 지난 뒤에는 어떤 항목도 새로 시작되지 않으며, 이미 시작된 제출은 중간에 끊기지 않습니다. 시작되지 않은 항목은 제출되지 않은 것으로 나열됩니다. 배치를 마무리하려면 첫 제출 후 24시간 이내에 같은 client_request_id와 완전히 같은 inputs로 다시 호출하세요. 결과에 마저 제출해야 한다고 나열된 항목이 제출되고, 이미 접수된 항목은 새로 과금되지 않고 원래 작업을 반환합니다. 그때까지 pricing_quote가 만료되었다면 같은 입력으로 예상 비용을 다시 산정하고 새 값을 전달하세요. 결과를 알 수 없는 항목은 나중에 같은 방법으로 재시도하거나 list_tasks를 확인하세요. 이 24시간 안에는 접수된 항목, 제출되지 않은 항목, 결과를 알 수 없는 항목을 새 client_request_id로 다시 제출해서는 안 됩니다. 그렇게 하면 새 작업이 만들어지고 요금이 부과됩니다. 그 기간이 지나면 같은 client_request_id로도 두 번째 과금을 막을 수 없습니다. 먼저 list_tasks를 확인한 뒤, 접수되지 않은 항목만 새 예상 비용과 새 client_request_id를 사용해 새 배치로 제출하세요. 그 client_request_id로 이전에 제출한 것과 입력이 다른 항목은 거부됩니다(idempotency_conflict). 그런 항목은 별도의 예상 비용, 승인, client_request_id가 필요한 새 작업입니다.
get_task
error.code), API도 반환하는 설명(error.message), 그리고 billing_note를 반환합니다. 이 작업에는 요금이 부과되지 않으며, 제출 시 선차감된 크레딧은 자동으로 반환됩니다. 원본 결과는 보통 24시간 동안 보관됩니다. 미리보기 표시 여부는 호스트 클라이언트에 따라 다릅니다.
list_tasks
get_task_usage
check_balance
인수가 없습니다:upload_file
prepare_upload
필수file_name: 미디어 유형을 판별하는 데 쓰이는 확장자가 포함된 문자열. 선택 upload_path: 상대 디렉토리.
get_upload
필수upload_id: 원래 prepare 결과에서 받은 값입니다:
결과와 오류
도구는 읽을 수 있는 텍스트와 structuredContent를 반환하며, 실패한 경우 isError/error/next_step이 포함될 수 있습니다. 완료된 미디어에는 resource_link와 선택적인 이미지 썸네일이 포함될 수 있습니다. 콘텐츠 블록 지원 범위는 호스트마다 다릅니다. 전달의 기준은 여전히 원본 URL이며, 모든 호스트에서 미리보기가 보장되지는 않습니다. 도구 오류와 함께 input_valid, 예상 비용 상태, task.status 같은 비즈니스 필드를 확인하세요. HTTP 200만으로는 생성에 성공했다고 볼 수 없습니다. 제출 시간 초과는 작업이 생성된 뒤에 발생할 수도 있으므로, 요금이 부과되지 않았다는 증거가 아닙니다. 조회가 실패했다고 해서 원래 작업이 실패했다는 증거는 아닙니다.작업 진행 상황과 결과
무료 연결 검증에는 잔액 조회와 모델 조회를 사용하세요. 기존 작업에는 get_task/list_tasks를 사용한 뒤 원본 URL과 보고된 실제 비용을 전달하세요. 참조 파일, 복구, 저장, 회색 미리보기는 작업 흐름 가이드에서 다룹니다. 표시 문제 때문에 유료 생성을 다시 해서는 안 됩니다.MCP 프로토콜과 백엔드 API
원격 엔드포인트는
https://mcp.evolink.ai/mcp입니다. OAuth는 Passport가 제공하며, 서버는 https://api.evolink.ai 및 파일 서비스에 요청을 보냅니다. MCP URL, 플랫폼 /v1 경로, 문서, llms.txt는 서로 다른 진입점입니다.
초기화와 도구 호출
initialize, 프로토콜 버전, Accept, 인증, 세션, 콘텐츠 블록은 호스트나 MCP SDK가 처리하게 하세요. 초기화가 끝난 뒤 tools/list를 읽고 tools/call을 호출하세요:도구와 백엔드 동작
모델 매개변수는 arguments.input에 넣으며, 서버가 REST 요청으로 변환합니다. media_seconds는 과금 계산용 힌트이고, max_cost_usd는 제출 전에 예상 비용만 검사합니다. 정식 출시된 1.12.1은 공개 가격 규칙으로 예상 비용을 산정하며(참고 가격, 계정 할인 미포함), 여전히 최종 정산 금액의 상한은 없습니다.