AI 에이전트 연결

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

공개 테스트넷 MCP

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

MCP 연결

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

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

Claude Code

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 설정

Claude Desktop / claude.ai

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

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

Claude 원격 커넥터 설정

Cursor

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

.cursor/mcp.json

{
  "mcpServers": {
    "pouchi": {
      "url": "https://mcp.15-164-50-132.sslip.io/mcp"
    }
  }
}

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

Cursor MCP 설정

Hermes

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

~/.hermes/config.yaml

mcp_servers:
  pouchi:
    url: "https://mcp.15-164-50-132.sslip.io/mcp"
    auth: oauth
    timeout: 300

hermes mcp login pouchi
hermes mcp list
hermes mcp test pouchi

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

Hermes 원격 MCP 설정

다른 MCP 클라이언트

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

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

지갑 연결과 첫 결제

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 구성을 사용합니다. 공개 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와의 차이

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

다음 단계

• 위임 결제: 한도가 지갑 컨트랙트에서 어떻게 지켜지는지
• 서비스 MCP 구현: 내 가게를 에이전트 결제에 붙이기
• intent와 권한: intent_url의 형식과 권한 범위
• 지갑 MCP 도구 레퍼런스