🤖 MCP 통합

개요

MCP(Model Context Protocol)는 AI 에이전트가 외부 도구를 호출할 수 있게 해주는 표준입니다. 플러그 MCP 서버를 Claude에 연결하면 의뢰/계약/정산 등 플러그 데이터를 LLM 명령으로 다룰 수 있습니다. 연결 방법은 두 가지입니다.

방법	대상	인증
주소로 연결 (권장)	Claude 웹·데스크톱·모바일, Claude Code	플러그 로그인 후 업체 선택
API Key로 설치	Claude Desktop(macOS), Cursor 등 로컬 MCP 클라이언트	API Key

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

주소로 연결

설치 없이 MCP 서버 주소만 등록하면 됩니다. 연결할 때 플러그에 로그인하고 업체 하나를 골라 허용합니다.

https://mcp-api.pluuug.com/mcp

연결은 업체 하나 단위입니다. 여러 업체를 쓴다면 연결할 때 하나를 고르고, 다른 업체는 따로 연결하세요. Claude 유료 요금제(Pro·Max·Team·Enterprise)가 필요합니다.

개인 Claude (Pro·Max)

플러그에서 연결 시작

플러그 개인 설정 > AI 연결에서 **[Claude에 연결]**을 누르면 Claude 화면이 열립니다. 이름과 주소가 채워진 상태에서 추가합니다.Claude에서 직접 추가하려면 Customize > Connectors에서 커스텀 커넥터를 추가하고 위 주소를 넣으세요.

업체 선택 후 허용

플러그 화면으로 넘어오면 연결할 업체를 고르고 **[연결하기]**를 누릅니다.

대화에서 사용

Claude로 돌아가면 연결이 끝납니다. “최근 의뢰 5건 보여줘”처럼 물어보세요.

회사 Claude (Team·Enterprise)

회사 Claude는 조직 소유자(Owner)가 커넥터를 먼저 추가하고, 멤버가 각자 연결합니다.

조직 소유자: 커넥터 추가 (한 번만)

Claude Organization settings > Connectors에서 Add > Custom > Web을 누르고 이름 “플러그”, 위 주소를 넣습니다.OAuth Client ID·Secret은 비워 두고, 방식을 묻는 화면이 나오면 Sign in now와 Use Claude’s published identity를 고르세요.

각 멤버: 연결

Claude Customize > Connectors에서 “플러그”를 찾아 Connect를 누르고, 플러그에 로그인해 업체를 골라 **[연결하기]**를 누릅니다.

권한과 해제

연결한 사람은 고른 업체의 데이터를 조회하고 수정할 수 있습니다. 데이터를 바꾸거나 지우는 도구는 Claude가 실행 전에 확인을 받습니다.
업체에서 빠지거나 멤버가 비활성화되면 연결은 즉시 끊깁니다.
연결 해제: 플러그 개인 설정 > AI 연결 목록에서 해제하거나, Claude Customize > Connectors에서 연결을 끊습니다.
플랜에 따라 일부 도메인은 사용할 수 없습니다(아래 PLAN_PERMISSION_DENIED 참고).

API Key로 설치

Claude Desktop(macOS)에 로컬 MCP 서버를 설치하는 방법입니다. 주소로 연결을 지원하지 않는 MCP 클라이언트에서도 이 방식을 씁니다.

사전 준비

API Key 발급

플러그 설정 화면에서 API Key를 발급합니다. API 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 대화형 입력
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, 호출 로그 도메인이 모두 사용 가능합니다.

트러블슈팅

❌ 연결 화면에 원하는 업체가 없습니다

그 업체의 활성 멤버인 계정으로 로그인했는지 확인하세요. 다른 계정으로 로그인돼 있다면 플러그에서 로그아웃한 뒤 다시 연결합니다.

❌ 연결 후 다시 로그인하라는 메시지가 나옵니다

연결을 해제했거나, 업체에서 빠졌거나, 오래 사용하지 않아 연결이 만료된 경우입니다. Claude에서 Connect를 다시 눌러 연결하세요.

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

PLUUUG_API_KEY 값이 잘못되었거나 누락된 경우, 또는 키를 재발급해 이전 키가 무효가 된 경우입니다.해결: 설정 화면의 API Key가 맞는지 확인하고, 위 설치 명령을 다시 실행해 키를 갱신하세요. 기존 설정은 자동 백업됩니다.

❌ 403 PLAN_PERMISSION_DENIED

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

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

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

❌ 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를 사용하고, 플러그 백엔드 호출 시 X-API-KEY 헤더를 자동으로 붙입니다.

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

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

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

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

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

요금이 부과되나요?

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

API Reference

개요

주소로 연결

개인 Claude (Pro·Max)

회사 Claude (Team·Enterprise)

권한과 해제

API Key로 설치

사전 준비

설치 (1줄 명령)

Claude Desktop 재기동

동작 검증

트러블슈팅

FAQ

관련 자원

​개요

​주소로 연결

​개인 Claude (Pro·Max)

​회사 Claude (Team·Enterprise)

​권한과 해제

​API Key로 설치

​사전 준비

​설치 (1줄 명령)

​Claude Desktop 재기동

​동작 검증

​트러블슈팅

​FAQ

​관련 자원

개요

주소로 연결

개인 Claude (Pro·Max)

회사 Claude (Team·Enterprise)

권한과 해제

API Key로 설치

사전 준비

설치 (1줄 명령)

Claude Desktop 재기동

동작 검증

트러블슈팅

FAQ

관련 자원