콘텐츠로 이동
PouchiPouchi개발 문서
요금문서EN

AI 에이전트 연결

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

MCP 연결

섹션 제목: “MCP 연결”
https://mcp.15-164-50-132.sslip.io/mcp

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

터미널 창
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 설정

지갑 연결과 첫 결제

섹션 제목: “지갑 연결과 첫 결제”

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

    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으로 요청하세요. 응답에 topup_url이 있으면 표시된 자산을 확인해 충전한 뒤 잔액을 다시 확인합니다.

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

    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 체험에서 티켓리와 세이브온으로 이동할 수 있습니다.

도구

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

인자와 결과 상태는 지갑 MCP 도구 레퍼런스에 있습니다.

에이전트 제한 사항

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

자주 겪는 오류

섹션 제목: “자주 겪는 오류”
응답 뜻 해결
waiting_for_user와 approval_url 오류가 아님. 이용자 승인을 기다리는 중 링크를 열어 승인. 에이전트는 payment_status(job_id)를 다시 부름
needs_topup (INSUFFICIENT_BALANCE) 지갑 잔액이 결제 금액보다 적음 응답의 필요 자산과 네트워크를 확인. 충전 안내를 따르거나 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으로 초대를 요청
USE_SERVICE_MCP 지갑 MCP에 가게 결제를 직접 요청함 서비스 MCP의 buy로 intent_url을 받아 pay_intent에 전달
승인 링크에 “만료된 요청이에요” 연결 요청의 유효 시간이 지남 wallet_login을 다시 불러 새 링크를 받음

고급: 로컬 stdio

섹션 제목: “고급: 로컬 stdio”

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

~/.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와의 차이

섹션 제목: “개발자 MCP와의 차이”

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

다음 단계

섹션 제목: “다음 단계”

Pouchi 개발 문서Pouchi Homellms.txtShard Lab