🤖 MCP 통합 - 플러그 개발자 센터

개요

MCP(Model Context Protocol)는 AI 에이전트가 외부 도구를 호출할 수 있게 해주는 표준입니다. 플러그가 제공하는 MCP 서버를 자기 컴퓨터에 띄우면 Claude Desktop, Cursor 등에서 의뢰/계약/정산 등 플러그 데이터를 LLM 명령으로 다룰 수 있습니다.

예시: “이번 달 신규 의뢰 보여줘”, “ABC 회사 계약 상세 알려줘”, “오늘 마감인 Todo 생성해줘” 같은 자연어 요청을 LLM이 알아서 플러그 API로 변환합니다.

사전 준비

API Key + Secret Key 발급

플러그 관리자 페이지에서 발급합니다. Secret Key는 발급 직후 1회만 표시되므로 안전한 곳(1Password, OS 키체인 등)에 즉시 저장하세요.

Secret Key를 잃어버리면 재발급이 필요합니다. 발급 즉시 저장하세요.

Claude Desktop 설치

공식 사이트에서 다운로드: https://claude.ai/download

Python 의존성(uv)이 없으면 아래 설치 명령이 자동으로 설치합니다. 별도 사전 준비는 필요 없습니다.

설치 (1줄 명령)

터미널을 열고 다음 명령을 실행하세요. 키 입력 prompt가 나오면 발급받은 값을 붙여넣으면 됩니다.

curl -fsSL https://raw.githubusercontent.com/postoo-io/pluuug-openapi-mcp/main/scripts/install.sh | bash

스크립트가 자동으로 수행하는 작업:

macOS / Claude Desktop 설치 확인
uv 자동 설치 (미설치 시)
API Key / Secret Key 대화형 입력
Claude Desktop 설정 파일 백업 + pluuug MCP 서버 등록
wrapper 다운로드 + 의존성 설치 (20~40초)
Claude Desktop 재기동 안내

설치 전에 스크립트 내용을 확인하고 싶다면 — scripts/install.sh에서 코드 전문을 볼 수 있습니다. 검증 후 실행하려면:

curl -O https://raw.githubusercontent.com/postoo-io/pluuug-openapi-mcp/main/scripts/install.sh
shasum -a 256 install.sh   # 게시된 hash와 대조
bash install.sh

현재 macOS만 지원합니다. Windows/Linux는 추후 지원 예정입니다.

Claude Desktop 재기동

설치 직후 Claude Desktop을 완전히 재기동해야 새 MCP 서버가 인식됩니다.

완전 종료

화면 상단 메뉴바의 [Claude] 메뉴 → [Claude 종료]

창의 빨간 X 버튼만 누르면 안 됩니다. 메뉴바 트레이에 살아있으면 설정이 적용되지 않습니다.

다시 실행

Spotlight(Cmd+Space) 또는 Launchpad에서 Claude를 다시 실행합니다.

동작 검증

Claude Desktop 새 대화에서 다음과 같은 자연어를 입력해보세요:

"내 비즈니스의 최근 의뢰 5건 보여줘"

LLM이 자동으로 의뢰 목록 tool(inquiry_list)을 호출하고 결과를 보여주면 정상 동작입니다.

노출 도구 수: 약 72개. 의뢰, 계약, 정산, 고객, 견적, 프로젝트, Todo, 실무자, 멤버, 폴더, 커스텀 필드, Presigned URL, 호출 로그 도메인이 모두 사용 가능합니다.

트러블슈팅

❌ 모든 호출이 403으로 실패합니다

PLUUUG_SECRET_KEY 값이 잘못되었거나 누락된 경우입니다. HMAC 서명을 만들 수 없어 백엔드가 거부합니다.해결: 발급받은 Secret Key가 맞는지 확인하고, 위 설치 명령을 다시 실행해 키를 갱신하세요. 기존 설정은 자동 백업됩니다.

❌ 401 인증 실패

PLUUUG_API_KEY 값이 잘못되었거나 누락된 경우입니다.해결: 관리자에서 발급받은 API Key가 맞는지 확인하고, 위 설치 명령을 다시 실행해 키를 갱신하세요.

❌ 403 PLAN_PERMISSION_DENIED

플랜 제약입니다. 일부 도메인은 특정 플랜에서만 사용 가능합니다:

project / worker: FREE 또는 AGENCY 플랜 전용
member: FREE / TEAM / AGENCY 플랜 전용

플랜 업그레이드 또는 사용 가능한 다른 도구를 사용하세요.

❌ Secret Key를 잃어버렸어요

Secret Key는 정책상 발급 시 1회만 표시됩니다. 잃어버린 경우 관리자에서 새 API Key를 재발급해야 합니다.재발급 후 위 설치 명령을 다시 실행해 키를 갱신하세요(기존 설정 자동 백업).

❌ 429 Too Many Requests

분당 호출 한도(1,000회)를 초과했습니다. 호출 빈도를 조정하거나 잠시 대기 후 다시 시도하세요.

❌ 'Tool execution failed' 같은 메시지가 나옵니다

Claude Desktop이 wrapper 응답을 거부하는 케이스입니다. wrapper(pluuug-openapi-mcp)가 최신이면 보통 자동 우회됩니다.해결: 위 설치 명령을 다시 실행하면 wrapper 최신 버전을 받아옵니다. 문제 지속 시 GitHub Issue에 환경 정보(macOS 버전 / Claude Desktop 버전 / 명령)를 포함해 등록해 주세요.

❌ install.sh 실행이 실패합니다

스크립트가 도중에 멈춘 경우 출력된 에러 메시지를 확인하세요. 자주 발생하는 케이스:

Claude Desktop이 설치돼 있지 않습니다 → https://claude.ai/download에서 먼저 설치
python3가 PATH에 없습니다 → xcode-select --install로 Command Line Tools 설치
uv 설치 후 PATH에서 찾을 수 없습니다 → 새 터미널을 열고 다시 시도

그래도 해결되지 않으면 출력 전문을 Issue에 첨부해 주세요.

FAQ

이 패키지의 소스 코드는?

MCP wrapper (실행 코드): github.com/postoo-io/pluuug-openapi-mcp (MIT)
설치 스크립트: scripts/install.sh

wrapper는 내부적으로 awslabs/openapi-mcp-server를 사용하고, 플러그 백엔드 호출 시 HMAC-SHA256 서명을 자동으로 추가합니다.

Cursor / Continue 등 다른 MCP 클라이언트에서도 쓸 수 있나요?

네. MCP 표준 stdio 프로토콜을 따르므로 MCP를 지원하는 모든 클라이언트에서 사용 가능합니다.단, 본 install.sh는 Claude Desktop 설정 파일을 기준으로 작성됐습니다. 다른 클라이언트는 wrapper README를 참고해 직접 등록하세요.

HMAC 서명을 직접 구현해야 하나요?

아니요. wrapper가 매 요청마다 자동으로 X-Signature를 계산해 헤더에 추가합니다. 키 두 개를 설정에 넣어두면 끝입니다.

키 회전(rotation)은 어떻게 하나요?

관리자에서 새 API Key 발급
위 설치 명령을 다시 실행 (curl -fsSL ... | bash)
기존 설정은 자동 백업되고 새 키로 덮어쓰기됩니다
Claude Desktop 완전 종료 후 재시작

구 키는 더 이상 사용 불가합니다.

요금이 부과되나요?

플러그 API 호출 정책에 따릅니다. 상세는 별도 안내 페이지 또는 영업 담당자에 문의하세요.

​개요

​사전 준비

​설치 (1줄 명령)

​Claude Desktop 재기동

​동작 검증

​트러블슈팅

​FAQ

​관련 자원

개요

사전 준비

설치 (1줄 명령)

Claude Desktop 재기동

동작 검증

트러블슈팅

FAQ

관련 자원