x402 MCP 도구 데모 — 실제 402, 실제 거부, 실제 정산

x402 결제 프로토콜이 MCP 스타일 도구 엔드포인트를 보호하는 최소 데모로, 실제 x402==2.16.0 Python 패키지와 기본 공개 facilitator(https://x402.org/facilitator)를 Base Sepolia 테스트넷에서 사용해 실행합니다. 여기에는 손으로 작성한 프로토콜 JSON이 없습니다. captured_responses/의 모든 응답은 편집 없이 라이브러리에서 나온 것입니다.

함께 보면 좋은 자료: MCP 도구에 요금을 청구하는 방법: 1시간 안에 작동하는 x402 엔드포인트.

구성 요소

Related MCP server: 402-mcp

실행하기

pip install -r requirements.txt
python gen_wallets.py          # writes wallets.json (gitignored) -- two fresh, empty keys
python server.py               # starts on 127.0.0.1:8402
python client_probe.py         # in a second terminal

확인할 내용

라운드 1 — 지불 없음. payment-required 헤더(base64 JSON)가 있는 402: 스킴, 네트워크, 자산 컨트랙트, 토큰의 가장 작은 단위의 금액, 그리고 지불할 주소.

라운드 2 — 실제 서명된 지불, 잔액 0. 클라이언트는 일회용 키로 실제 EIP-3009 인증을 구성하고 서명한 뒤, 이를 X-PAYMENT로 첨부합니다. 그러면 facilitator가 실제 Base Sepolia 체인 상태와 대조하여 확인합니다. 그 결과는 다음과 같습니다:

{ "error": "invalid_exact_evm_insufficient_balance" }

이 문자열은 facilitator의 실제 오류 코드이지 추측이 아닙니다 — 프로토콜이 설계된 대로 정확히 작동하고 지불자가 단순히 돈이 없을 때 얻는 결과입니다.

라운드 3 — 자금이 충전되어 실제로 정산됨. agent_address에 Circle 공개 faucet에서 20 테스트넷 USDC를 충전한 후, 같은 서버에 대해 client_probe.py를 다시 실행했습니다. 이번에는 라운드 2가 200으로 돌아옵니다:

{
  "url": "https://example.com/mcp",
  "recommendation": "expose as a priced x402 tool at $0.01/call",
  "paid": true
}

그리고 payment-response 헤더를 디코딩하면:

{ "success": true, "payer": "0x3214cB6C...E0E9", "transaction": "0x9530b663...0dd86", "network": "eip155:84532" }

해당 트랜잭션 해시는 실제이며 독립적으로 검증할 수 있습니다 — Base Sepolia Blockscout에서 보기: 상태 ok, USDC 컨트랙트로 전송, 메서드 transferWithAuthorization — 지불자가 서명한 정확한 EIP-3009 가스리스 전송 패턴입니다. 이 README를 신뢰하지 않아도 누구나 확인할 수 있습니다.

client_probe.py에서 수동 라운드 트립을 하는 이유

x402 2.16.0에는 PaymentRoundTripper가 포함되어 있지만, 이는 커스텀 httpx/requests 트랜스포트에 연결하도록 설계된 콜백(handle_response(...))입니다 — docstring이 암시하는 것과 달리 그 자체로 바로 사용할 수 있는 트랜스포트는 아닙니다. client_probe.py는 내부적으로 호출하는 동일한 세 가지 기본 요소(get_payment_required_response → create_payment_payload → encode_payment_signature_header)를 직접 호출하므로 데모에 필요한 구성 요소가 더 적고 동일한 와이어 출력을 생성합니다.

안전 참고 사항

• gen_wallets.py는 eth_account.Account.create()로 키를 생성합니다 — 암호학적으로 무작위이며, 이 데모에서 자금이 충전되거나 메인넷에 닿는 일이 없습니다.

• wallets.json은 gitignore되어 있습니다. wallets.example.json은 잘 알려진 소각(burn) 주소로 형태를 보여 주므로, git 기록에 비밀값 없이 깨끗한 클론에서도 저장소를 실행할 수 있습니다.

• facilitator URL, 네트워크, 자산 컨트랙트는 라이브러리 자체의 테스트넷 기본값입니다 — 여기서는 Base 메인넷과 통신하거나 실제 가치를 이동하지 않습니다.