a2a-x402-mcp-services

실제 에이전트 간(A2A) 상거래를 위한 프로덕션 지향 x402 v2 수익화 MCP 도구입니다.

• 실제 온체인 결산(모의 구현 없음, 시뮬레이션 결제 없음)

• 현재 x402 v2 사양 완전 준수(CAIP-2 네트워크, PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE 헤더, x402Version: 2, 정확한 스킴)

• 공식 @x402/mcp + @x402/core + @x402/evm 패키지

• Bazaar 지원(Bazaar 확장을 구현한 파실리테이터를 통해 도구 검색 가능)

• 실제 생태계 격차를 해소하기 위해 구축: 에이전트가 실제로 재구독하는 운영 유틸리티

현재 유료 도구

모든 도구는 정확한 결제 스킴을 사용하며 실제 파실리테이터를 통해 결제합니다.

Related MCP server: Agent Commerce Suite

x402 v2 준수 체크리스트

• x402Version: 2

• CAIP-2 네트워크 식별자(eip155:8452 Base Sepolia 기본값, eip155:8453 메인넷용)

• 공식 헤더(PAYMENT-REQUIRED, PAYMENT-SIGNATURE, PAYMENT-RESPONSE)

• @x402/evm/exact를 통한 정확한 스킴

• 파실리테이터 기반 검증 + 결제(프로세스 내 자체 결제 금지)

• MCP 도구 검색을 위한 Bazaar 확장 메타데이터

• 환경 변수 기반 payTo 주소(하드코딩된 프로덕션 지갑 없음)

빠른 시작(테스트넷)

git clone https://github.com/Disseveru/a2a-x402-mcp-services.git
cd a2a-x402-mcp-services
npm install

# Required: receiving wallet (Base Sepolia)
export X402_PAY_TO_EVM=0xYourTestnetAddress

# Optional overrides
# export X402_NETWORK=eip155:84532
# export X402_FACILITATOR_URL=https://x402.org/facilitator
# export PORT=4022

npm run dev

상태 확인(무료):

curl http://localhost:4022/health

도구 카탈로그(무료):

curl http://localhost:4022/tools

MCP 엔드포인트(유료):

POST http://localhost:4022/mcp

x402 v2를 인식하는 모든 MCP 클라이언트(@x402/mcp 클라이언트 헬퍼, CDP 관리형 지갑 등)를 사용하세요. 유료 도구에 대한 첫 번째 호출은 적절한 402를 받게 됩니다. 클라이언트는 서명하고 PAYMENT-SIGNATURE로 재시도하며, 파실리테이터가 결제하고, 도구 결과가 반환됩니다.

메인넷으로 전환하기

1. 메인넷 수신 주소를 설정합니다:

   export X402_PAY_TO_EVM=0xYourMainnetAddress

2. 네트워크를 전환합니다:

   export X402_NETWORK=eip155:8453

3. 프로덕션 파실리테이터(예시 – CDP)를 사용합니다:

   export X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402

   (선택한 파실리테이터가 요구하는 경우 CDP 자격 증명을 제공합니다.)

4. 서버를 시작합니다. 실제 USDC가 이동합니다.

잃어도 감수할 수 있는 금액보다 더 많이 보유한 핫키로 메인넷을 실행하지 마십시오.

아키텍처

src/
  config.ts          – env-driven CAIP-2 + facilitator + payTo
  server.ts          – McpServer + official createPaymentWrapper (@x402/mcp)
  tools/
    definitions.ts   – paid tool implementations (real logic)
  index.ts           – Express host + Streamable HTTP MCP transport

설계 원칙

1. 모의 없음 – 모든 유료 경로는 실제 파실리테이터 결제 호출로 종료됩니다.

2. v2 전용 – 레거시 X-PAYMENT 헤더나 v1 네트워크 문자열이 없습니다.

3. 운영 유틸리티 – 도구는 반복 구매하는 에이전트 문제(위험, 정규화, 파실리테이터 선택)를 해결합니다.

4. 검색 가능 – 에이전트가 URL을 하드코딩하지 않고 도구를 찾을 수 있도록 Bazaar 메타데이터가 포함되어 있습니다.

5. 운영자 안전 – 수신 주소와 네트워크는 환경 변수에서만 가져옵니다.

라이선스

MIT