# AI 어시스턴트(MCP)

> Claude Code, Cursor, Codex에서 요청 하나로 판매를: 내 키로 도는 로컬 MCP 서버를 통해 상품, 가격, 결제 링크, 테스트 결제.

`perly-pay-mcp`를 쓰면 어시스턴트가 Perly Pay를 대신 설정합니다: 상품과 가격을 만들고, 결제 링크를 공유하고, [테스트 모드](https://pay.perly.io/docs/test-mode.md)에서 결제한 뒤 도착한 것을 보여 줍니다. 내 컴퓨터에서 돌며 내 키로 Perly Pay API와만 통신합니다. 중간에 저희 것은 아무것도 없습니다.

## 설정

1. **테스트 키 받기** — Dashboard → Developers → API keys: `sk_test_…`. 이 키로 만드세요 — 실제 돈은 움직이지 않습니다.
2. **서버 추가** — Claude Code에서는 한 줄, Cursor나 Codex 설정에서는 몇 줄. Node 20 이상이 필요합니다.
3. **요청하기** — "1시간 상담을 $49에 결제 링크로 팔고, 테스트 모드에서 결제한 뒤 결제 내역을 보여 줘."

**Claude Code**

```bash
claude mcp add perly-pay --env PERLY_PAY_SECRET_KEY=sk_test_… -- npx -y perly-pay-mcp
```

**Cursor**

```json
// ~/.cursor/mcp.json, or .cursor/mcp.json in a project
{
  "mcpServers": {
    "perly-pay": {
      "command": "npx",
      "args": ["-y", "perly-pay-mcp"],
      "env": { "PERLY_PAY_SECRET_KEY": "sk_test_…" }
    }
  }
}
```

**Codex**

```toml
# ~/.codex/config.toml
[mcp_servers.perly-pay]
command = "npx"
args = ["-y", "perly-pay-mcp"]
env = { PERLY_PAY_SECRET_KEY = "sk_test_…" }
```

> **주의:** 키를 git에 넣지 마세요: 프로젝트의 설정 파일은 커밋되는 경우가 많습니다.

| 변수 | 의미 |
| --- | --- |
| `PERLY_PAY_SECRET_KEY` | 만드는 동안은 `sk_test_…`. `sk_live_…`는 읽기만 합니다(아래 참고). |
| `PERLY_PAY_API` | 기본값 `https://pay.perly.io`. |
| `PERLY_PAY_WEBHOOK_SECRET` | 선택: `verify_webhook_signature`용 `whsec_…`. |

## 도구

[API](https://pay.perly.io/docs/api.md) 명세에서 생성되므로 모든 인수는 API가 받는 그대로입니다. 금액은 센트 단위 정수입니다: `4900`은 $49.00.

| 도구 | 용도 |
| --- | --- |
| `create_product`, `list_products`, `update_product`, `create_price`, `list_prices`, `update_price` | 상품과 가격 |
| `create_payment_link`, `list_payment_links`, `update_payment_link` | 결제 링크 |
| `create_invoice`, `list_invoices`, `retrieve_invoice`, `cancel_invoice`, `create_checkout_session`, `retrieve_checkout_session` | 청구서와 결제창 |
| `create_customer`, `list_customers`, `retrieve_customer` | 고객 |
| `create_subscription`, `list_subscriptions`, `retrieve_subscription` | 구독 |
| `check_entitlement`, `list_entitlements`, `consume_entitlement_credits`, `list_credit_usage` | 이용권과 크레딧 |
| `list_payments`, `retrieve_payment`, `list_receipts`, `retrieve_receipt`, `list_events` | 결제, 영수증, 이벤트 |
| `create_refund`, `list_refunds` | 환불 |
| `create_webhook_endpoint`, `list_webhook_endpoints`, `delete_webhook_endpoint` | 웹훅 |
| `simulate_payment` | 테스트 모드 |
| `verify_webhook_signature`, `pay_links` | 내 컴퓨터에서 |

`simulate_payment`는 청구서를 결제하거나 결제 링크로 구매해 결제하므로, 실제 구매자처럼 이행, 영수증, [웹훅](https://pay.perly.io/docs/webhooks.md)이 동작합니다. `pay_links`는 나만 할 수 있는 일을 위한 대시보드 페이지를 알려 줍니다.

## 하지 않는 것

- **라이브 키로는 읽기만 합니다.** 쓰는 도구는 모두 거부됩니다: 새 청구서, 결제 세션, 상품, 가격, 고객, 링크, 구독, 수정, 취소, 환불, 크레딧 차감, 웹훅. 도구가 이유를 알려 주며, 대시보드나 앱 자체 코드에서 하시면 됩니다. 이유: 구매자가 입력한 글이 어시스턴트에 닿을 수 있고, 서버가 받는 어떤 것도 실제 변경을 승인한 것이 모델이 아니라 당신이라는 것을 증명하지 못하기 때문입니다.
- **지갑, API 키, 내 청구서, 라이브 모드 전환, 2단계 로그인**에는 도구가 없습니다. 대시보드에서 직접 하세요. `pay_links`가 페이지를 알려 줍니다.
- **되돌릴 수 없는 일** — 청구서 취소, 환불 시작, 웹훅 삭제 — 은 `confirm: true`를 기다리며, 어시스턴트는 내 동의 후에만 보냅니다.
- **내 비밀 키는 응답에도 로그에도 절대 다시 나오지 않습니다.**

## 라이브로 전환

1. **지갑 연결** — 대시보드에서 공개 키나 주소를. 시드 문구나 개인 키는 절대 요청하지 않습니다. [지갑](https://pay.perly.io/docs/wallets.md)을 보세요.
2. **라이브 모드 켜기** — 지갑이 연결되면 대시보드에서.
3. **키 바꾸기** — 앱 서버에서 `sk_test_…` 대신 `sk_live_…`를 쓰세요. 어시스턴트에는 테스트 키를 그대로 둬도 됩니다.