MCP 문제 해결

다시 시도하기 전에 도구 검색, 인증, 조직 접근 권한, 인수, 결과가 불확실한 작업을 점검하세요.

증상에 따라 다음으로 확인할 항목을 정하세요. 도구가 보이지 않으면 연결을 살펴보고, 호출이 거부되면 인수나 권한 오류를 확인하세요. 도구 이름, 기밀이 아닌 입력값, 응답, 관련 리소스 또는 소스 리비전을 보관하세요. 이 자료가 있으면 결과가 불확실한 쓰기 작업을 반복하지 않고도 원래 의도한 작업을 복구하는 데 도움이 됩니다.

필요한 도구가 보이지 않음 #

설정된 엔드포인트와 클라이언트가 반환한 도구 목록을 비교하세요. /mcp와 /main는 인증을 거쳐 사용하는 동일한 도구를 제공합니다. /account는 인증 후 /main로 리디렉션합니다.

members_listMemberships와 engines_list를 찾아 첫 조회 예제를 따라 해 보세요. 정확한 이름과 스키마는 현재 tools/list 응답에서 확인하세요. API 엔드포인트가 있다고 해서 MCP에서도 제공된다는 뜻은 아닙니다.

일부 도구만 보이지 않는다면 클라이언트의 허용 목록과 승인 설정을 살펴보고 작업에 필요한 도구만 활성화하세요. 있어야 할 도구가 없다면 문제를 보고할 수 있도록 서버와 버전 정보, 기밀이 아닌 도구 검색 결과를 보관하세요.

GET 요청에 405가 반환됨 #

/mcp에서 스트리머블 HTTP를 설정하세요. 인증 후 /mcp 또는 /main에 GET 요청을 보내면 Allow: POST와 함께 405가 반환됩니다. 클라이언트는 POST로 MCP 메시지를 보냅니다. 토큰이 없거나 유효하지 않으면 요청을 처리 대상으로 전달하기 전에 401이 반환됩니다. 반면 /account에 인증된 요청을 보내면 /main로 리디렉션하는 308이 반환됩니다. 이러한 GET 응답만으로는 유효한 MCP POST 연결이 작동하는지 확인할 수 없습니다. 올바른 전송 방식을 선택한 뒤 클라이언트의 연결 오류를 살펴보세요.

인증 또는 조직이 올바르지 않음 #

401의 경우, 연결 과정에서 의도한 Lingo.dev 사용자로 OAuth 인증을 완료했는지 확인하세요. 호스팅 서버에는 유효한 사용자 베어러 토큰이 필요합니다. 개인용 또는 서비스용 API 키는 x-api-key에서도, 베어러 값으로도 사용할 수 없습니다. 클라이언트가 인증을 갱신하도록 하거나 계정 관리에서 다시 연결하세요. 진단 정보에 토큰을 포함하지 마세요.

members_listMemberships를 호출하고 data에서 원하는 조직을 선택한 다음, 해당 조직의 ID를 다음 도구의 조직 필드에 전달하세요. engines_list에서는 해당 필드가 orgId입니다. 같은 목록에서 다른 조직을 선택할 때는 OAuth 인증을 다시 할 필요가 없습니다. 다른 사용자로 로그인되어 있다면 다시 연결하세요. 재시작만 하면 저장된 세션이 재사용될 수 있습니다.

ssoRequired에 멤버십이 표시된다면 해당 조직의 ID 공급자를 통해 Lingo.dev에 로그인한 후 다시 연결하세요. data와 ssoRequired가 모두 비어 있다면 https://lingo.dev/orgs/start에서 조직 설정을 완료한 다음 멤버십을 다시 조회하세요. 이용할 수 없는 조직은 존재하지 않거나, 사용자가 속해 있지 않거나, SSO가 필요한 조직일 수 있습니다. 이런 응답을 모두 자격 증명이 만료되었다는 뜻으로 해석하지 마세요.

도구가 권한이나 이용 자격을 이유로 요청을 거부하면 인증을 반복하지 말고 해당 작업의 요구 사항을 확인하세요. 조직 접근 권한과 특정 쓰기 작업을 수행할 권한은 별도로 확인됩니다. 더 넓은 권한을 가진 역할이나 자격 증명을 알리지 않고 임의로 선택하지 말고, 어떤 권한이 부족한지 설명하세요.

도구에서 조직 설정이 완료되지 않았다고 표시됨 #

최근 생성된 조직으로, 생성자가 웹 앱에서 연동, 팀원, 첫 엔진 설정을 아직 완료하지 않은 상태입니다. 설정이 끝날 때까지 조직 수준 도구의 사용이 제한될 수 있습니다. 다시 시도하거나 인증을 다시 해도 이 단계가 완료되지는 않습니다. members_listMemberships는 계속 사용할 수 있습니다. 조직 생성자 계정으로 메시지에 있는 링크인 https://lingo.dev/orgs/<orgId>를 열고, 메시지에 안내된 단계를 완료한 다음 다시 호출하세요. 새 조직 설정 완료하기를 참고하세요.

도구에서 인수를 거부함 #

입력값을 연결에서 반환한 정확한 스키마와 비교하세요. 현재 도구 인수는 평면 필드 구조이며, 중첩 값은 스키마에 정의된 위치에 그대로 둡니다. 임의로 body, params 또는 query 래퍼를 추가하지 마세요. 조직 필드가 필요하면 명시적으로 전달하세요. 이 필드는 베어러 토큰에서 자동으로 채워지지 않습니다. 선택 항목인 intent는 작업을 설명하는 필드입니다. 지원되는 계정 작업은 지원 기능을 참고하세요.

각 ID가 무엇을 식별하는지 확인하세요. members_remove.id는 members_list의 멤버십 ID이고, members_setRole.userId는 해당 멤버십의 사용자를 식별합니다. 로컬라이제이션 엔진 ID를 요청 로그 ID 대신 사용할 수는 없습니다. 불투명 커서나 정밀도가 온전히 유지된 타임스탬프와 ID 쌍은 화면에 표시된 날짜로 재구성하지 말고 그대로 복사하세요.

스키마에서 구분하는 생략된 값과 널 값, 숫자와 문자열, 배열과 단일 값의 차이를 유지하세요. 인수 오류를 우회하려 하기 전에 연결된 도구의 스키마를 확인하세요.

계정 쓰기 작업이나 작업 실행 결과가 불확실함 #

다시 시도하기 전에 관련 리소스나 작업 상태를 조회하세요. 서버가 키 생성, 초대, 검토 결정, 제안 또는 작업을 수락한 뒤에도 네트워크 오류가 발생할 수 있습니다. 자동으로 다시 제출하지 말고 의도한 변경이 실제로 반영되었는지 확인하세요.

제출한 프로비저닝 작업은 다시 시도할지 결정하기 전에 저장해 둔 작업 ID로 provisioningJobs_get를 조회하세요. 다른 작업은 저장된 리소스와 연결된 도구에 명시된 완료 조건을 살펴보세요. 번역 워크플로는 CLI 또는 API 레퍼런스를 참고하세요.

문서 또는 근거 자료가 없음 #

localization_search로 검색한 다음, 검색 결과의 path를 docs_fetch에 전달해 전체 페이지를 읽으세요. 해당 경로로 접근할 수 없다면 수행하려는 작업을 다시 검색하고 최신 결과를 사용하세요. 지식 베이스는 파일 기반 웹사이트와 별도의 저장 경로를 사용하므로, 색인에 웹사이트 페이지가 없거나 오래된 내용이 남아 있을 수 있습니다. 기능을 사용할 수 없다고 결론 내리기 전에 현재 웹사이트의 레퍼런스를 확인하세요.

해결되지 않은 MCP 기능 공백을 보고할 때는 시도한 작업, 정확한 도구 이름, 서버 버전, 기밀이 아닌 응답을 포함하세요. 보고가 접수되었다고 해서 수정 일정이 보장되는 것은 아닙니다.

품질에 관한 문의라면 소스 근거 자료, 완료된 평가, 적용 가능한 기준, 명확한 답변 중 무엇이 부족한지 파악하세요. 각각 필요한 후속 조치가 다릅니다. 측정에서는 답을 얻지 못한 사례를 통과로 간주하지 않으면서 확보한 근거 자료를 보고하는 방법을 설명합니다.