# AI 에이전트 연결

Claude Code, Hermes 같은 MCP 클라이언트의 에이전트가 이용자가 승인한 한도 안에서만 결제하도록 지갑 MCP를 연결합니다.

에이전트는 결제를 요청만 합니다. 이용자는 Pouchi 승인 화면에서 받는 곳, 금액, 횟수, 기간을 확인하고 PIN이나 패스키로 한 번 승인합니다. 그 뒤 에이전트의 결제는 승인한 한도 안에서만 실행되고, 한도는 지갑 컨트랙트가 확인합니다.

**공개 테스트넷 MCP**

아래 URL 하나를 추가하면 지갑 도구 9개와 `shop_*` 쇼핑 도구를 함께 쓸 수 있습니다. 로컬 서버나 설치 스크립트는 필요하지 않습니다. 현재 공개 주소는 Maroo Testnet(450815)에 연결된 스테이징 서비스입니다.

## MCP 연결

```text wrap
https://mcp.15-164-50-132.sslip.io/mcp
```

클라이언트에 이 URL을 Streamable HTTP 서버로 추가하고 브라우저에서 연결을 승인합니다. OAuth 2.1(자동 클라이언트 등록 DCR, authorization code + PKCE)을 지원하는 클라이언트가 필요합니다. MCP 연결 승인과 Pouchi 지갑 로그인은 별도입니다.

  **Claude Code**

```sh
claude mcp add --transport http pouchi https://mcp.15-164-50-132.sslip.io/mcp
claude mcp list
```

Claude Code를 실행하고 `/mcp`에서 `pouchi`를 선택해 인증합니다. 브라우저에서 연결을 승인한 뒤 도구 목록에서 `wallet_status`, `pay_intent`, `shop_*`를 확인합니다. `claude mcp list`에 인증이 필요하다고 나오면 아직 연결 승인이 끝나지 않은 상태입니다.

[Claude Code MCP 설정](https://code.claude.com/docs/en/mcp)

  **Claude Desktop / claude.ai**

커넥터(Connectors)에서 커스텀 커넥터 추가(Add custom connector)를 선택합니다. 이름은 `Pouchi`, 원격 MCP 서버 URL은 위 주소로 입력합니다. Web 커넥터 유형을 묻는 화면에서도 같은 URL을 씁니다.

OAuth 인증을 선택하고, OAuth 클라이언트 옵션이 보이면 자동 등록(Register automatically)을 선택합니다. 연결을 승인한 다음 대화에서 Pouchi 커넥터를 켭니다. 팀 계정에서는 관리자가 먼저 커넥터를 추가해야 할 수 있습니다.

[Claude 원격 커넥터 설정](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)

  **Cursor**

프로젝트의 `.cursor/mcp.json`에 추가합니다. 모든 프로젝트에서 쓰려면 `~/.cursor/mcp.json`에 넣습니다.

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "pouchi": {
      "url": "https://mcp.15-164-50-132.sslip.io/mcp"
    }
  }
}
```

Cursor를 다시 열고 MCP 설정에서 `pouchi`의 OAuth 연결을 승인합니다. Agent의 도구 목록에 지갑 도구와 `shop_*`가 함께 표시되는지 확인합니다.

[Cursor MCP 설정](https://docs.cursor.com/context/model-context-protocol)

  **Hermes**

`~/.hermes/config.yaml`의 `mcp_servers`에 원격 URL을 추가합니다.

```yaml title="~/.hermes/config.yaml"
mcp_servers:
  pouchi:
    url: "https://mcp.15-164-50-132.sslip.io/mcp"
    auth: oauth
    timeout: 300
```

```sh
hermes mcp login pouchi
hermes mcp list
hermes mcp test pouchi
```

로그인 명령이 여는 브라우저에서 연결을 승인하고 새 Hermes 대화를 시작합니다. 별도 프로필을 쓰면 그 프로필의 설정을 고치고 `hermes -p 프로필명`으로 명령을 실행합니다.

[Hermes 원격 MCP 설정](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)

  **다른 MCP 클라이언트**

서버 이름을 `Pouchi`, URL을 위 공개 주소, 전송 방식을 Streamable HTTP로 설정합니다. OAuth 자동 등록(DCR)과 PKCE를 켜고 브라우저에서 연결을 승인합니다. 쇼핑 서버를 따로 추가할 필요는 없습니다.

도구 목록에 지갑 도구 9개와 `shop_*`가 보이면 MCP 연결이 끝난 상태입니다. 별도 입력창을 여는 MCP elicitation 기능은 필요하지 않습니다. 지갑 로그인과 결제 승인은 도구 응답의 텍스트 링크로 진행합니다.

## 지갑 연결과 첫 결제

1. 지갑 상태를 확인합니다. MCP 연결 후 에이전트에게 이렇게 말합니다.

```text wrap
pouchi의 wallet_status를 호출해 줘.
connected:false이고 next_tool이 wallet_login이면 wallet_login을 호출해 줘.
응답의 user_message와 approval_url을 보여 줘. 링크는 내가 열어서 로그인할게.
waiting_for_user이면 반환된 job_id로 payment_status를 호출해 기다려.
연결이 끝나면 wallet_status로 지갑 주소와 잔액을 보여 줘.
```

`wallet_status`의 `connected:false`는 지갑 로그인이 필요하다는 뜻입니다. `wallet_login`이 텍스트로 반환하는 `approval_url`을 열고 Pouchi 화면에서 로그인을 마칩니다.

결제 전에 `wallet_status` 응답의 자산과 잔액을 확인합니다. SDK 송금 예시는 네이티브 테스트 OKRW를 쓰며, 쇼핑 데모는 별도 결제 토큰을 쓸 수 있습니다. 자금이나 초대가 필요하면 지갑 주소, 네트워크와 데모 이름을 적어 [business@pouchi.app](mailto:business@pouchi.app)으로 요청하세요. 응답에 `topup_url`이 있으면 표시된 자산을 확인해 충전한 뒤 잔액을 다시 확인합니다.

2. 상품을 고르고 결제를 요청합니다. 같은 MCP의 `shop_*` 도구로 상품을 조회하고 결제 요청을 만듭니다.

```text wrap
pouchi의 shop_* 도구로 상품을 보여 줘. 내가 상품을 고르면
해당 쇼핑 도구로 intent_url을 만들고 pay_intent에 전달해 줘.
응답의 user_message와 approval_url을 보여 줘.
링크에서 받는 곳, 금액, 횟수, 기간을 확인하고 내가 승인할게.
waiting_for_user이면 반환된 job_id로 payment_status를 호출해 기다려.
```

`pay_intent`도 승인 링크와 안내를 텍스트로 반환합니다. 사용자 인증(패스키, PIN 등)은 Pouchi 승인 화면에서 합니다. 채팅에 쓴 "승인"은 결제 승인이 아닙니다.

3. 결과와 남은 한도를 확인합니다. `my_payments`로 결제 결과와 영수증을, `my_budget`으로 남은 한도와 횟수를 봅니다. 같은 한도 안의 다음 결제는 다시 묻지 않고 실행됩니다.

## 기대 결과

승인 화면에는 요청한 에이전트, 가게, 금액, 승인 범위가 나옵니다. 승인 전에 각 항목을 확인하세요. [Pouchi 체험](/docs/tour/)에서 티켓리와 세이브온으로 이동할 수 있습니다.

## 도구

| 도구 | 언제 |
|---|---|
| `wallet_login` | 지갑 가입이나 로그인과 연결. 이용자가 승인 화면에서 마침 |
| `wallet_status` | 지갑 주소, 잔액, 승인한 권한 |
| `pay_intent` | 서비스가 준 `intent_url` 실행. 지갑 MCP에서 결제를 시작하는 도구 |
| `change_mandate` | 구독 연장이나 한도 증액처럼 권한을 바꿀 때 (이용자 승인 필요) |
| `my_budget` | 승인한 권한, 남은 한도와 횟수, 기간 |
| `my_payments` | 결제 내역과 영수증 |
| `revoke_mandate` | 게이트웨이 결제를 즉시 중지. 체인 해지 승인 링크가 반환되면 이용자가 승인해 마침 |
| `wallet_disconnect` | 지갑 연결 끊기. 이 지갑으로 연결된 에이전트는 더 결제하지 못함 |
| `payment_status` | 승인 대기 작업의 결과 기다리기. 한 번에 최대 50초 |

인자와 결과 상태는 [지갑 MCP 도구 레퍼런스](/docs/reference/wallet-mcp/)에 있습니다.

## 에이전트 제한 사항

- 채팅에 "승인"이라고 써서 결제를 승인하기. 승인은 승인 화면에서만 됩니다.
- 등록되지 않은 사이트가 만든 결제 요청 실행하기. 게이트웨이는 등록된 서비스 주소에서만 intent를 가져옵니다.
- 승인한 한도 넘기. 지갑 컨트랙트가 금액, 횟수, 기간을 체인에서 다시 확인합니다.

**결제 전용 에이전트 권장**

결제하는 에이전트에 셸, 파일, 웹 도구를 함께 켜면 프롬프트 주입의 영향이 커집니다. 한도가 피해를 제한하지만, 도구는 필요한 것만 켜세요.

## 자주 겪는 오류

| 응답 | 뜻 | 해결 |
| --- | --- | --- |
| `waiting_for_user`와 `approval_url` | 오류가 아님. 이용자 승인을 기다리는 중 | 링크를 열어 승인. 에이전트는 `payment_status(job_id)`를 다시 부름 |
| `needs_topup` (`INSUFFICIENT_BALANCE`) | 지갑 잔액이 결제 금액보다 적음 | 응답의 필요 자산과 네트워크를 확인. 충전 안내를 따르거나 [business@pouchi.app](mailto:business@pouchi.app)으로 테스트 자금을 요청. 잔액 확인 후 재시도 |
| `OVER_LIMIT` | 1회 한도, 남은 한도, 남은 횟수 중 하나를 넘음 | 서비스가 만든 한도 변경 intent를 `change_mandate`로 보내고 이용자가 다시 승인 |
| `PERIOD_LIMIT` | 이번 기간의 횟수나 금액을 다 씀 | 응답의 `next_period_at` 이후 다시 요청 |
| `MANDATE_EXPIRED` | 승인한 권한의 기간이 끝남 | 새 `intent_url`로 `pay_intent`를 불러 다시 승인 |
| `WALLET_DISCONNECTED` | 이용자가 지갑 연결을 끊음 | `wallet_login`으로 다시 연결 |
| `TESTER_REQUIRED` | 초대 전용 데모에 초대되지 않은 계정 | [business@pouchi.app](mailto:business@pouchi.app)으로 초대를 요청 |
| `USE_SERVICE_MCP` | 지갑 MCP에 가게 결제를 직접 요청함 | 서비스 MCP의 `buy`로 `intent_url`을 받아 `pay_intent`에 전달 |
| 승인 링크에 "만료된 요청이에요" | 연결 요청의 유효 시간이 지남 | `wallet_login`을 다시 불러 새 링크를 받음 |

## 고급: 로컬 stdio

저장소를 직접 개발하는 경우에만 로컬 stdio 구성을 사용합니다. 공개 URL로 연결할 때는 이 단계가 필요하지 않습니다. 로컬 API, 게이트웨이와 서비스 서버는 별도로 준비해야 하며, 아래 설정은 지갑 MCP 프로세스만 실행합니다. 승인은 Pouchi 화면에서 합니다.

```yaml title="~/.hermes/config.yaml"
mcp_servers:
  agentpay:
    command: "node"
    args: ["/path/to/agent-pay/apps/local-wallet/server.mjs"]
    env:
      AGENT_PAY_WALLET_HOME: "/Users/<you>/.agent-pay/local-wallet"
      REGISTRY_PATH: "/path/to/agent-pay/registry/shops.tkrw.json"
```

## 개발자 MCP와의 차이

앱 연동 코드를 AI 코딩 도구가 쓰게 하려면 [개발자 MCP](/docs/ai/)(`pouchi-dev`)를 씁니다. 문서 검색, 예시 코드, 연동 점검 도구가 있고 지갑 결제 도구는 없습니다.

## 다음 단계

- [위임 결제](/docs/delegation/): 한도가 지갑 컨트랙트에서 어떻게 지켜지는지
- [서비스 MCP 구현](/docs/services/): 내 가게를 에이전트 결제에 붙이기
- [intent와 권한](/docs/intents/): `intent_url`의 형식과 권한 범위
- [지갑 MCP 도구 레퍼런스](/docs/reference/wallet-mcp/)