API 및 MCP 연결 문제 해결

올바른 연결과 인증 정보 사용

MCP는 공개 베타로 운영됩니다. OAuth 없이 브라우저에서 URL을 열면 인증 응답이 나올 수 있습니다. 일반 HTML 페이지가 아니므로 그 자체가 장애 증거는 아닙니다.

MCP OAuth 대신 API 키를 넣거나 웹 로그인 토큰을 API 키로 쓰거나 임의의 /sse를 붙이지 마세요. MCP 클라이언트 설정을 따르세요.

로그인은 성공했는데 도구가 실패

계정 인증 완료, 개발자 접근 중지 여부, 필요한 권한 부여 여부를 확인하세요. 유료 생성이라면 크레딧 잔액도 확인하세요.

폐기된 권한, 누락된 범위, 호환되지 않는 인증 흐름은 잔액과 별도로 해결해야 합니다. 필요하면 공식 절차로 재연결하세요. 클라이언트 오류를 우회하려고 PKCE나 리디렉션 검증을 약화하지 마세요.

첫 읽기 전용 검사로 list_models를 사용하세요. 성공은 연결·읽기 권한만 검증하며 업로드, 생성 승인, 전체 출력 품질을 보장하지 않습니다.

업로드 또는 다운로드가 미완료

원격 서버는 로컬 경로를 읽지 못합니다. prepare_image_upload 후 승인된 별도 클라이언트 기능으로 실제 바이트를 보내고 complete_image_upload에서 사용 가능한 파일 ID를 받아야 합니다.

download_asset도 메타데이터·임시 URL을 반환하며 파일을 컴퓨터에 저장한 상태가 아닙니다. API/OAuth 인증 정보를 전달하지 않고 바이트를 다운로드하세요. 클라이언트에 기능이 없으면 제한을 알리고 승인된 지원 대안을 사용하세요.

견적 및 지출 거부

quote_id, max_credits는 request 옆에 놓는 MCP 도구 인수이며 공개 API 본문 필드가 아닙니다. 작업별 상한은 세션 전체 예산이 아닙니다. 지출 안전장치를 참고하세요.

불확실한 생성 요청의 안전한 복구

요청, 멱등 키, 계정, 인증 식별(API의 API 키 ID, MCP의 OAuth 클라이언트)을 유지하세요. 키·클라이언트를 바꿔도 중복 방지가 따라온다고 가정하지 마세요.

생성 재시도 전에 알려진 작업을 조회하세요. 재시도 가능 여부와 제공되는 API Retry-After를 따르세요. MCP 구조화 오류에는 해당 HTTP 헤더가 보장되지 않습니다. 재시도와 로컬 대기에는 한도를 두세요.

로컬 시간 초과는 원격 작업을 취소하지 않습니다. 종료 실패에도 부분 출력·비용이 있을 수 있습니다. 지원팀에는 요청·작업 ID, 시간, 코드, 클라이언트 종류, 실패 단계를 비공개로 전달하고 비밀값·서명 링크는 제외하세요.