MCP 연결 설정

인증된 계정의 도구에 연결한 뒤 조직과 도구 목록을 확인하세요.

어시스턴트를 Lingo.dev 계정에 연결한 뒤 읽기 요청으로 원하는 조직이 맞는지 확인하세요. 서버는 로그인한 Lingo.dev 사용자의 권한으로 작동합니다.

계정 연결 #

원격 서버 URL을 https://mcp.lingo.dev/mcp로 설정하고 OAuth를 사용하는 스트리밍 가능한 HTTP를 선택하세요. 클라이언트에서 권한 부여 절차를 시작하고, 연결하려는 Lingo.dev 계정에 로그인한 뒤 연결을 승인하세요. 클라이언트는 MCP 엔드포인트에서 권한 부여 서버를 찾고 액세스 및 갱신 자격 증명을 관리합니다.

MCP 요청은 Authorization: Bearer <access-token>에 사용자 액세스 토큰을 담아 전송합니다. 이 토큰은 영구적인 개인 API 키가 아니며, 특정 조직에 종속되지도 않습니다. 백엔드는 각 도구가 지정한 리소스에 사용자가 접근할 권한이 있는지 확인합니다. 이러한 권한과 자격 증명 처리 방식은 계정 자격 증명에서 설명합니다.

x-api-key에 넣은 API 키나 베어러 값으로 사용한 API 키로는 이 호스팅 서버에 인증할 수 없습니다. API 키를 정적 헤더에 복사하는 대신, 서버의 OAuth 연결을 지원하는 클라이언트를 사용하세요.

연결에 필요한 값을 아래에 정리했습니다. 이 표는 특정 클라이언트용 설정 파일이 아닙니다:

json
{
  "endpoint": "https://mcp.lingo.dev/mcp",
  "transport": "Streamable HTTP",
  "authentication": "OAuth user session"
}

이 값을 클라이언트에서 지원하는 필드에 맞게 입력하세요. 인증 정보 저장 방식과 설정 구문은 버전에 따라 다릅니다. 엔드포인트는 MCP POST 요청을 받습니다. 유효한 토큰이 없으면 OAuth 검색 메타데이터와 함께 401를 반환하고, 인증된 GET 요청에는 405 Method Not Allowed를 반환합니다. 브라우저에서 URL을 여는 것만으로는 초기화된 MCP 연결을 테스트할 수 없습니다.

기존 호스팅 URL #

https://mcp.lingo.dev/main는 동일한 도구와 사용자 권한을 제공합니다. OAuth 검색 절차가 /mcp와 다르므로, 정상적으로 작동하는 /main 연결은 기존 권한 부여 설정을 그대로 사용해도 됩니다. /mcp로 이전할 때는 새 연결로 추가하고 해당 URL의 OAuth 절차를 완료하세요. 이전 연결에 저장된 권한 부여 설정을 새 URL과 혼용하지 마세요.

이전 주소인 https://mcp.lingo.dev/account는 유효한 사용자 토큰을 받기 전까지 401를 반환합니다. 유효한 토큰을 받으면 요청 메서드와 본문을 유지한 채 308 응답으로 /main에 리디렉션합니다. 이 리디렉션으로 API 키 인증이나 조직에 종속된 이전 도구 목록이 복원되지는 않습니다. API 키가 저장된 연결을 이전할 때는 OAuth로 다시 연결하세요.

새 조직 설정 완료 #

새 계정으로 연결할 때는 웹 앱에서 조직 이름을 지정합니다. 그런 다음 조직을 만든 사용자가 웹 앱에서 연동, 팀원, 첫 번째 엔진의 세 가지 추가 단계를 완료합니다. 웹 앱은 조직 웹사이트의 정보를 바탕으로 첫 번째 엔진을 채웁니다. 연동과 팀원 단계는 건너뛸 수 있습니다. 세 단계를 모두 마치기 전까지는 해당 조직을 지정하는 모든 도구가 남은 단계와 https://lingo.dev/orgs/<orgId> 링크를 안내하는 오류를 반환합니다. 링크를 열면 조직을 만든 사용자가 현재 진행 중인 단계로 이동합니다. members_listMemberships에는 조직이 계속 표시되므로 어시스턴트가 조직 ID를 찾을 수 있습니다.

링크를 열어 설정 단계를 마친 뒤 다시 호출하세요. 이후에는 어시스턴트가 정상적으로 작동하며, engines_create 또는 provisioningJobs_create로 엔진을 더 만들 수 있습니다. 초대받은 구성원과 이 설정 절차가 도입되기 전에 생성된 조직에는 영향이 없습니다.

계정 범위 확인 #

  1. 클라이언트의 도구 목록을 열고 members_listMemberships와 engines_list를 찾으세요.
  2. members_listMemberships를 호출해 사용자가 속한 조직을 조회하세요. 조직이 하나뿐이면 해당 조직을 사용하세요. 여러 개라면 원하는 조직을 선택하고, 이 작업에 사용할 조직 ID를 보관하세요.
  3. 해당 조직의 orgId를 전달해 engines_list를 호출한 뒤, 반환된 data에서 엔진 ID를 선택하세요.
  4. 선택한 도구를 사용하기 전에 각 도구가 공개한 스키마를 읽으세요. 조직 수준 도구에는 조직을 명시하는 필드가 필요하며, 개체 수준 도구에는 대신 리소스 ID를 전달할 수 있습니다. 쓰기 작업은 합의된 작업 범위 안에서만 수행하세요.

동일한 소속 목록에 있는 조직 사이를 전환할 때는 OAuth 연결을 새로 만들 필요가 없습니다. orgId 또는 조직 id 등 도구가 지정한 필드에 선택한 ID를 전달하세요. 서버는 토큰에서 고정된 조직을 가져와 자동으로 지정하지 않습니다. 의도한 사용자와 다른 계정으로 로그인되어 있다면 클라이언트의 계정 관리에서 다시 연결하세요.

members_listMemberships #

이 호출에는 조직 ID가 필요하지 않습니다. intent는 작업을 설명하는 선택 항목입니다:

json
{
  "intent": "Find the organization whose French translation guidance I should inspect."
}

응답의 data에는 접근 가능한 조직의 ID와 이름이 포함됩니다. 선택적으로 포함되는 ssoRequired 항목은 현재 세션에서 아직 수행하지 않은 SSO 로그인이 필요한 소속을 나타냅니다. 해당 조직의 ID 공급자를 통해 Lingo.dev에 로그인한 뒤 다시 연결하세요. ssoRequired에 있는 조직은 아직 일반적인 조직 수준 호출에서 사용할 수 없습니다.

두 목록이 모두 비어 있으면 https://lingo.dev/orgs/start를 열어 첫 번째 조직을 설정한 뒤 이 읽기 요청을 다시 실행하세요. 기존 소속에 SSO 로그인이 필요하다는 이유만으로 조직 ID를 지어내거나 두 번째 조직을 만들지 마세요.

engines_list #

org_example를 소속 조회 응답에서 받은 ID로 바꾸세요:

json
{
  "orgId": "org_example",
  "intent": "Find the localization engine used for French translations."
}

이후 엔진 수준 읽기 작업에는 반환된 data의 엔진 ID를 사용하세요. 이 값들은 도구에 전달하는 전체 인수이며, HTTP 요청 본문을 감싸는 래퍼가 아닙니다. 도구는 작업별 필드와 함께 선택 항목인 intent를 사용합니다. 계정에서 수행할 수 있는 작업은 기능을 참고하세요.

클라이언트별 설정 위치 #

설정 구문과 지원되는 전송 방식은 클라이언트의 최신 문서를 참고하세요. 두 클라이언트가 같은 엔드포인트를 사용하더라도 이러한 선택은 중요합니다.

클로드 코드 #

/mcp에 연결할 때는 원격 OAuth HTTP 연결을 선택하세요. 저장하기 전에 연결을 사용자 설정에 둘지 프로젝트 설정에 둘지 결정하세요. 프로젝트 공유 설정에는 자격 증명을 포함하지 마세요. 각 사용자가 자신의 계정 연결을 직접 승인해야 합니다. 연결을 활성화한 뒤 도구 목록을 확인하세요.

코덱스 #

코덱스는 TOML 설정을 사용하며, 설정 파일은 보통 ~/.codex/config.toml에 있습니다. 사용 중인 버전에서 지원하는 원격 MCP 기능으로 계정 URL을 설정하세요. 다른 클라이언트의 JSON을 TOML에 그대로 옮기지 마세요. 해당 버전에서 전송 브리지가 필요하다면 사용하기 전에 브리지 자체의 인증 방식과 토큰 저장 방식을 확인하세요. 브리지 역시 자격 증명을 보유하는 별도의 프로세스입니다.

커서 #

사용자 수준 설정과 프로젝트 .cursor/mcp.json 중 어디에 설정할지 신중하게 선택하세요. 프로젝트 연결을 사용하면 팀원들이 서버 정의를 찾을 수 있지만, 실제 계정 키를 공유해서는 안 됩니다. 각 사용자가 자신의 계정 연결을 직접 승인해야 합니다.

Claude Desktop 및 claude.ai #

Lingo.dev는 클로드 커넥터 디렉터리에 등록되어 있어 URL이나 설정 파일이 필요하지 않습니다. Claude Desktop과 claude.ai에서의 절차는 동일합니다:

  1. 설정 > 맞춤 설정 > 탐색을 여세요.
  2. Lingo.dev를 검색하고 Lingo.dev 커넥터에서 연결을 클릭하세요.
  3. Lingo.dev 권한 부여 페이지에서 연결하려는 계정에 로그인하고 승인을 클릭하세요.

클로드가 자격 증명을 저장하고 갱신합니다. 연결한 뒤 도구 목록을 확인하세요.

챗지피티 #

원격 맞춤 앱의 사용 가능 여부와 OAuth 지원 여부는 계정과 클라이언트 버전에 따라 다릅니다. 지원되는 경우 /mcp URL을 사용하고, 연결하려는 Lingo.dev 사용자 계정으로 권한을 부여하세요.

에이전트에게 범위가 명확한 첫 작업 맡기기 #

첫 요청은 다음과 같이 작성할 수 있습니다:

선택한 로컬라이제이션 엔진의 프랑스어 용어집과 지침을 살펴보세요. 어떤 리소스가 연결되어 있는지, 해당 리소스가 제가 제공한 제품 용어를 다루고 있는지 설명하세요. 변경 사항은 적용하기 전에 먼저 제안하세요. 이 작업은 번역, 제안 생성, 키 생성 또는 구성원 관리를 허용하지 않습니다.

이 지침을 클라이언트 측 승인 기능이나 적절한 도구 허용 목록과 함께 사용하세요. 프롬프트는 요청하는 작업을 정의할 뿐, 자격 증명에 부여된 쓰기 권한을 제거하지는 않습니다.

검색이나 첫 읽기 요청이 실패하면 문제 해결을 참고해 해결한 뒤 계속 진행하세요.