> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openapi.pluuug.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 🤖 MCP 통합

> Claude Desktop, Cursor 등에서 플러그 API를 자동 호출하도록 MCP(Model Context Protocol) 서버를 설치합니다.

## 개요

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

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

## 사전 준비

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

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

  <Step title="Claude Desktop 설치">
    공식 사이트에서 다운로드: [https://claude.ai/download](https://claude.ai/download)
  </Step>
</Steps>

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

## 설치 (1줄 명령)

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

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/postoo-io/pluuug-openapi-mcp/main/scripts/install.sh | bash
```

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

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

<Tip>
  **설치 전에 스크립트 내용을 확인하고 싶다면** — [scripts/install.sh](https://github.com/postoo-io/pluuug-openapi-mcp/blob/main/scripts/install.sh)에서 코드 전문을 볼 수 있습니다. 검증 후 실행하려면:

  ```bash theme={null}
  curl -O https://raw.githubusercontent.com/postoo-io/pluuug-openapi-mcp/main/scripts/install.sh
  shasum -a 256 install.sh   # 게시된 hash와 대조
  bash install.sh
  ```
</Tip>

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

## Claude Desktop 재기동

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

<Steps>
  <Step title="완전 종료">
    화면 **상단 메뉴바**의 \[Claude] 메뉴 → \[Claude 종료]

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

  <Step title="다시 실행">
    Spotlight(Cmd+Space) 또는 Launchpad에서 Claude를 다시 실행합니다.
  </Step>
</Steps>

## 동작 검증

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

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

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

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

## 트러블슈팅

<AccordionGroup>
  <Accordion title="❌ 모든 호출이 403으로 실패합니다">
    `PLUUUG_SECRET_KEY` 값이 잘못되었거나 누락된 경우입니다. HMAC 서명을 만들 수 없어 백엔드가 거부합니다.

    **해결:** 발급받은 Secret Key가 맞는지 확인하고, 위 설치 명령을 다시 실행해 키를 갱신하세요. 기존 설정은 자동 백업됩니다.
  </Accordion>

  <Accordion title="❌ 401 인증 실패">
    `PLUUUG_API_KEY` 값이 잘못되었거나 누락된 경우입니다.

    **해결:** 관리자에서 발급받은 API Key가 맞는지 확인하고, 위 설치 명령을 다시 실행해 키를 갱신하세요.
  </Accordion>

  <Accordion title="❌ 403 PLAN_PERMISSION_DENIED">
    플랜 제약입니다. 일부 도메인은 특정 플랜에서만 사용 가능합니다:

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

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

  <Accordion title="❌ Secret Key를 잃어버렸어요">
    Secret Key는 정책상 발급 시 1회만 표시됩니다. 잃어버린 경우 관리자에서 **새 API Key를 재발급**해야 합니다.

    재발급 후 위 설치 명령을 다시 실행해 키를 갱신하세요(기존 설정 자동 백업).
  </Accordion>

  <Accordion title="❌ 429 Too Many Requests">
    분당 호출 한도(1,000회)를 초과했습니다. 호출 빈도를 조정하거나 잠시 대기 후 다시 시도하세요.
  </Accordion>

  <Accordion title="❌ 'Tool execution failed' 같은 메시지가 나옵니다">
    Claude Desktop이 wrapper 응답을 거부하는 케이스입니다. wrapper(`pluuug-openapi-mcp`)가 최신이면 보통 자동 우회됩니다.

    **해결:** 위 설치 명령을 다시 실행하면 wrapper 최신 버전을 받아옵니다.
    문제 지속 시 [GitHub Issue](https://github.com/postoo-io/pluuug-openapi-mcp/issues)에 환경 정보(macOS 버전 / Claude Desktop 버전 / 명령)를 포함해 등록해 주세요.
  </Accordion>

  <Accordion title="❌ install.sh 실행이 실패합니다">
    스크립트가 도중에 멈춘 경우 출력된 에러 메시지를 확인하세요. 자주 발생하는 케이스:

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

    그래도 해결되지 않으면 출력 전문을 [Issue](https://github.com/postoo-io/pluuug-openapi-mcp/issues)에 첨부해 주세요.
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="이 패키지의 소스 코드는?">
    * **MCP wrapper (실행 코드):** [github.com/postoo-io/pluuug-openapi-mcp](https://github.com/postoo-io/pluuug-openapi-mcp) (MIT)
    * **설치 스크립트:** [scripts/install.sh](https://github.com/postoo-io/pluuug-openapi-mcp/blob/main/scripts/install.sh)

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

  <Accordion title="Cursor / Continue 등 다른 MCP 클라이언트에서도 쓸 수 있나요?">
    네. MCP 표준 stdio 프로토콜을 따르므로 MCP를 지원하는 모든 클라이언트에서 사용 가능합니다.

    단, 본 install.sh는 Claude Desktop 설정 파일을 기준으로 작성됐습니다. 다른 클라이언트는 [wrapper README](https://github.com/postoo-io/pluuug-openapi-mcp#readme)를 참고해 직접 등록하세요.
  </Accordion>

  <Accordion title="HMAC 서명을 직접 구현해야 하나요?">
    아니요. wrapper가 매 요청마다 자동으로 X-Signature를 계산해 헤더에 추가합니다. 키 두 개를 설정에 넣어두면 끝입니다.
  </Accordion>

  <Accordion title="키 회전(rotation)은 어떻게 하나요?">
    1. 관리자에서 새 API Key 발급
    2. 위 설치 명령을 다시 실행 (`curl -fsSL ... | bash`)
    3. 기존 설정은 자동 백업되고 새 키로 덮어쓰기됩니다
    4. Claude Desktop 완전 종료 후 재시작

    구 키는 더 이상 사용 불가합니다.
  </Accordion>

  <Accordion title="요금이 부과되나요?">
    플러그 API 호출 정책에 따릅니다. 상세는 별도 안내 페이지 또는 영업 담당자에 문의하세요.
  </Accordion>
</AccordionGroup>

## 관련 자원

* **MCP wrapper:** [github.com/postoo-io/pluuug-openapi-mcp](https://github.com/postoo-io/pluuug-openapi-mcp)
* **설치 스크립트 소스:** [scripts/install.sh](https://github.com/postoo-io/pluuug-openapi-mcp/blob/main/scripts/install.sh)
* **API Reference:** [/api-reference](/api-reference) (전체 endpoint 목록)
* **인증 상세 (수동 구현 시):** [/authentication](/authentication)
* **MCP 표준:** [https://modelcontextprotocol.io](https://modelcontextprotocol.io)