개발자 문서

SosoAPI 설치: 패키지, 클라이언트, 원격 MCP

로컬 패키지 또는 호스팅 MCP로 에이전트를 SosoAPI에 연결하세요. 이 안내는 설치, 연결 확인, 업데이트를 다룹니다.

SosoAPI 팀 검토 · 2026-10-21

어떤 npm 패키지를 설치해야 하나요?

새 설정에는 sosoapi를 설치하세요. @sosoapi/cli, sosoapi-cli, sosoapi-mcp는 동일한 정확한 버전의 sosoapi를 설치하는 별칭입니다. 같은 CLI와 MCP 도구를 실행하므로 패키지는 하나만 있으면 됩니다.

로컬 MCP에는 Node.js 20 이상과 npm/npx가 필요합니다. 호스팅 MCP에는 로컬 패키지가 필요 없습니다. 설치 또는 연결 후 로그인하여 계정 접근을 부여하세요.

npm 배포 패키지
패키지	용도	명령
sosoapi	정식 CLI 및 MCP 서버	npx -y sosoapi --help
@sosoapi/cli	sosoapi의 정확한 버전에 연결된 별칭	npx -y @sosoapi/cli --help
sosoapi-cli	sosoapi의 정확한 버전에 연결된 별칭	npx -y sosoapi-cli --help
sosoapi-mcp	sosoapi의 정확한 버전에 연결된 별칭	npx -y sosoapi-mcp --help

로컬 MCP 클라이언트 연결

아래 명령으로 core 프로필 연결을 추가하세요. SosoAPI가 이미 연결되어 작동하면 해당 연결을 유지하세요. 인수 없이 sosoapi를 실행하면 stdio MCP 서버를 시작하고 stdin에서 클라이언트를 기다립니다.

Claude Desktop, Cursor 또는 다른 stdio 클라이언트는 MCP 설정에 아래 JSON을 추가하세요. 설정 위치와 승인 단계는 클라이언트마다 다릅니다. 필요하면 재시작 또는 재연결한 뒤 대화에서 SosoAPI 도구가 사용 가능한지 확인하세요.

claude mcp add sosoapi -e SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi

codex mcp add sosoapi --env SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi

{
  "mcpServers": {
    "sosoapi": {
      "command": "npx",
      "args": [
        "-y",
        "sosoapi"
      ],
      "env": {
        "SOSOAPI_TOOL_PROFILE": "core"
      }
    }
  }
}

MCP 도구 참조

OAuth로 원격 MCP 연결

원격 MCP, OAuth, 동적 클라이언트 등록을 지원하는 클라이언트에 아래 URL을 추가하세요. 브라우저에서 로그인하고 허용할 Workspace와 작업을 선택하세요. API 키, 클라이언트 ID, 클라이언트 비밀 값을 붙여 넣을 필요가 없습니다. HTTP로 미디어를 전달하려면 공개 URL을 가져오세요. 로컬 파일 업로드에는 로컬 MCP 서버가 필요합니다.

ChatGPT 맞춤 앱과 Claude 원격 커넥터는 요금제 및 클라이언트에서 가능한 커넥터 설정에 따라 다릅니다. 이 지침은 맞춤 연결 설정이며 앱 디렉터리 등록 설명이 아닙니다.

https://gqeshlawtcexsapabaui.supabase.co/functions/v1/remote-mcp

인증 및 권한

게시 없이 설정 검증

인증 상태를 확인하고 필요하면 로그인하세요. Workspace 컨텍스트와 연결 계정을 읽은 뒤 반환된 계정과 Workspace가 의도한 것인지 확인하세요. 게시물 제출 없이 접근을 검증하며, 게시는 해당 계정 권한에 따라 달라집니다.

설정을 완료하려고 테스트 게시물을 게시할 필요는 없습니다. 기존 콘텐츠로 원래 작업을 이어가세요. 사용자가 제공업체 동의를 완료하고 요청된 쓰기 전에 대상, 콘텐츠, 시간을 검토합니다.

npx sosoapi auth status

npx sosoapi api contract --route /identity-api/workspace/list --summary

버전 업데이트 또는 고정

npx -y sosoapi@latest --help를 실행하여 현재 CLI를 가져온 뒤 MCP 클라이언트를 다시 시작하세요. 클라이언트에 저장된 명령이 있으면 args에 원하는 버전을 지정하세요. 별칭은 정확한 sosoapi 버전에 연결되므로 별도의 전역 설치를 업데이트해도 바뀌지 않습니다.

버전 불일치 오류가 나오면 설치된 계약과 필요한 작업을 비교하세요. MCP 클라이언트가 실제 사용하는 명령의 패키지를 업데이트하고 다시 연결하여 작업을 재시도하세요. 스키마 불일치는 새 자격 증명이나 더 넓은 접근을 요구하지 않습니다.

npx -y sosoapi@latest --help

npx sosoapi api contract --summary

문제 해결