MCPay

MCPay는 AI 에이전트와 MCP 서버 사이에 위치합니다. 에이전트는 하나의 서버, 고정된 작업 목록, 정확한 가격, 예산, 만료 시간, nonce 범위에 연결된 단기 지출 토큰을 받습니다. 게이트웨이는 해당 정책을 검증하고, nonce를 원자적으로 클레임한 후, 업스트림 도구를 호출하고, 성공적으로 전달된 2xx 사용량을 내구성 있는 outbox에 기록합니다.

도구별 구독이 없습니다. 에이전트 내부에 크리에이터 API 키가 없습니다. 부동 소수점 금액이 없습니다.

베타 상태: 이 저장소는 폐쇄형, 실제 돈이 없는 베타를 운영합니다. 지갑 충전은 테스트 원장 크레딧입니다. Stripe 입금, 크리에이터 지급, KYC/AML, 분쟁, 세금 워크플로는 아직 포함되지 않습니다.

1. 에이전트는 예약된 지갑 잔액을 기반으로 지출 세션을 생성합니다.

2. MCPay는 정확한 서버, 작업 가격, 예산, 만료 시간, nonce 범위에 서명합니다.

3. 게이트웨이는 토큰을 검증하고 PostgreSQL에서 nonce를 클레임한 후 디스패치합니다.

4. 전달된 2xx 응답은 로컬 bbolt outbox에 들어가고 비동기적으로 정산됩니다.

저장소에는 Go API, 게이트웨이, 정산 워커, PostgreSQL 마이그레이션, 크리에이터 대시보드, JavaScript 및 Python SDK, 브라우저 테스트, Docker Compose 베타 스택이 포함됩니다. 실제 입금 및 지급은 의도적으로 비활성화되어 있습니다.

제품 둘러보기

컨트롤 플레인은 예약된 에이전트 예산, 크리에이터 수익, 유료 호출 볼륨, 로컬 권한 부여 지연 시간, 최근 정산 활동을 보여줍니다.

스크린샷은 고정된 문서 데이터 세트를 사용합니다. 수치는 프로덕션 지표가 아닙니다.

Related MCP server: MCP Gateway

MCPay가 존재하는 이유

10개의 유료 도구를 호출하는 에이전트는 10개의 구독, 10개의 결제 SDK, 10개의 장기 비밀 키가 필요하지 않아야 합니다. 크리에이터는 web_search에 5센트를 청구하기 전에 예약 로직, 재생 방지, 가격 확인, 영수증 저장, 정산 워커를 작성할 필요가 없어야 합니다.

MCPay는 실행 전에 지출 계약을 명시적으로 만듭니다:

클레임이 활성 세션과 일치하지 않으면 게이트웨이는 업스트림이 요청을 보기 전에 중지합니다.

비교

체크아웃은 쉬운 부분입니다. MCPay는 제한된 권한 부여, 호스트 간 중복 억제, 불변 가격, 취소 순서, 수락된 사용량의 내구성 있는 전달, 재시도 안전 정산을 처리합니다.

요청 경로

sequenceDiagram
    participant A as Agent
    participant C as MCPay API
    participant G as MCPay Gateway
    participant P as PostgreSQL
    participant T as MCP Tool
    participant W as Settlement Worker

    A->>C: Create spend session
    C->>P: Reserve budget and store price snapshot
    C-->>A: Ed25519-signed spend token
    A->>G: tools/call + token + nonce
    G->>G: Verify issuer, server, action, price, expiry
    G->>P: Atomic nonce claim
    P-->>G: Active and unique
    G->>P: Mark nonce dispatched
    G->>T: Execute tool
    T-->>G: Result
    G-->>A: Result
    G->>G: Persist delivered 2xx usage in bbolt outbox
    G->>C: Upload usage batch
    C->>P: Insert idempotent usage record
    W->>P: Settle creator credit

컨트롤 플레인 호출은 디스패치 전에 발생합니다. 오프라인 전용 재생 방지는 두 게이트웨이 머신을 조정하거나 취소된 세션을 중지할 수 없기 때문입니다. 서명 검사는 여전히 로컬에서 수행되므로 잘못된 형식 또는 범위를 벗어난 토큰은 데이터베이스 클레임에 도달하지 않습니다.

보안 모델

MCPay는 서명된 JWT를 "암호화"라고 부르지 않습니다. 그렇지 않습니다. 지출 토큰은 읽을 수 있는 클레임을 전달하고 Ed25519 서명을 사용하므로 게이트웨이는 서명 키를 보유하지 않고도 수정을 감지할 수 있습니다.

여기서 저장 시 암호화의 의미

MCPay는 원장 행에 애플리케이션 수준 필드 암호화를 추가하지 않습니다. PostgreSQL 자격 증명, 서명 키, 게이트웨이 비밀, 백업은 비밀 관리자 및 암호화된 저장소에 있어야 합니다. 관리형 PostgreSQL 또는 암호화된 호스트 볼륨은 데이터베이스 파일을 저장 시 보호해야 합니다. "모든 것이 암호화되어 있다"고 주장하면 실제 신뢰 경계가 숨겨지기 때문에 이 구분이 중요합니다.

베타 배포의 경우 PostgreSQL과 워커를 개인 네트워크에 유지하고, Caddy에서 공용 TLS를 종료하고, 런타임에 비밀을 마운트하고, 마이그레이션 전에 백업하고, deploy/.env.beta를 커밋하지 마세요.

로컬에서 실행

요구 사항: Compose v2가 있는 Docker Engine, 키 생성을 위한 Go 1.25+, 사용 가능한 메모리 4GB. Node.js 24는 대시보드 빌드 컨테이너 내에서 실행됩니다.

cp deploy/.env.beta.example deploy/.env.beta
go run ./cmd/mcpay-keygen

생성된 Ed25519 값을 deploy/.env.beta에 붙여넣고 모든 replace-* 값을 교체한 다음 스택을 시작하세요:

docker compose --env-file deploy/.env.beta -f deploy/compose.beta.yml config
docker compose --env-file deploy/.env.beta -f deploy/compose.beta.yml build
docker compose --env-file deploy/.env.beta -f deploy/compose.beta.yml up -d
docker compose --env-file deploy/.env.beta -f deploy/compose.beta.yml ps

http://localhost:8080을 엽니다. Compose 스택은 PostgreSQL, 마이그레이션, API, 워커, 대시보드, Caddy, 내부 TLS를 시작합니다. 테스트 충전은 가상 크레딧으로 유지됩니다.

실행 중인 스택 확인:

MCPAY_BETA_URL=http://localhost:8080 ./scripts/verify-central-beta.sh

PowerShell:

./scripts/verify-central-beta.ps1 -BaseUrl http://localhost:8080

배포 노트, 백업, DNS, Vercel/Supabase 옵션은 docs/central-beta-runbook.md 및 docs/beta-deployment.md에 있습니다.

MCP 서버 연결

Creator Studio에서 서버와 작업을 만들고, 서버 범위 게이트웨이 자격 증명을 발급한 다음, MCP 프로세스 옆에 있는 저장소에서 게이트웨이를 실행하세요:

go run ./cmd/mcpay-gateway \
  --target https://your-mcp-server.example \
  --mcp-path /mcp \
  --server-id srv_example \
  --environment beta \
  --token-issuer mcpay.beta \
  --public-key "$MCPAY_PUBLIC_KEY" \
  --control-plane-api https://api.example/v1/gateway/servers/srv_example \
  --nonce-claim-api https://api.example/v1/gateway/nonces/claim \
  --usage-api https://api.example/v1/usage-records \
  --usage-api-token "$MCPAY_GATEWAY_API_TOKEN" \
  --state-file ./mcpay-gateway.db

유료 요청은 두 개의 헤더를 전달합니다:

Authorization: Bearer <spend-token>
X-MCPay-Nonce: <nonce-within-the-signed-range>

게이트웨이는 요청을 업스트림으로 전달하기 전에 두 헤더를 모두 제거합니다.

에이전트 연결

MCPayAgentClient는 단기 세션을 생성하고 허용 목록에 있는 HTTPS 게이트웨이 출처에만 결제 헤더를 주입합니다:

import {
  FileAgentSessionCreationStore,
  MCPayAgentClient,
} from "@mcpay/sdk-js";

const paid = new MCPayAgentClient({
  apiBaseUrl: "https://pay.example.com/api/mcpay",
  accessToken: process.env.MCPAY_ACCESS_TOKEN!,
  walletId: process.env.MCPAY_WALLET_ID!,
  serverId: process.env.MCPAY_SERVER_ID!,
  reservedBudget: 50,
  gatewayOrigins: ["https://tools.example.com"],
  sessionCreationStore: new FileAgentSessionCreationStore(
    "./mcpay-agent-sessions.json",
  ),
});

const response = await paid.fetch("https://tools.example.com/mcp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
      name: "web_search",
      arguments: { query: "payment rails for MCP" },
    },
  }),
});

초기화 및 도구 검색은 지출 헤더 없이 통과합니다. 세션 생성은 멱등성 키를 사용하므로 응답이 손실되어도 예산이 두 번 예약되지 않습니다.

직접 SDK 래퍼

JavaScript 및 Python 래퍼는 개발 및 비공개 통합을 위해 존재합니다. 프로덕션 모드는 휘발성 사용을 거부합니다. 내구성 있는 게이트웨이가 권장 배포 경로로 남아 있는 이유는 nonce와 사용 상태를 프로세스 재시작 간에 유지하기 때문입니다.

import { MCPayClient } from "@mcpay/sdk-js";

const mcpay = new MCPayClient({
  publicKey: process.env.MCPAY_PUBLIC_KEY!,
  issuer: process.env.MCPAY_TOKEN_ISSUER!,
  serverId: process.env.MCPAY_SERVER_ID!,
  environment: "development",
  allowVolatileUsage: true,
});

export const paidSearch = mcpay.tool({
  name: "web_search",
  priceMinor: 5,
  handler: async (query: string) => search(query),
});

import os

from mcpay import MCPayClient

mcpay = MCPayClient(
    public_key=os.environ["MCPAY_PUBLIC_KEY"],
    issuer=os.environ["MCPAY_TOKEN_ISSUER"],
    server_id=os.environ["MCPAY_SERVER_ID"],
    environment="development",
    allow_volatile_usage=True,
)

@mcpay.tool(name="web_search", price_minor=5)
async def search(query: str):
    return await run_search(query)

검증

메인 브랜치는 Go, PostgreSQL 통합, 마이그레이션, 두 SDK, 브라우저 테스트, 패키지 빌드, 의존성 감사, 그리고 Docker Compose 구성을 확인합니다.

go test ./...
go test -race ./...
go vet ./...
go build ./cmd/...
npm ci
npm audit --audit-level=high
npm run build
npm run test
python -m pip install build
python -m build packages/sdk-python
python -m unittest discover -s packages/sdk-python/tests

PostgreSQL 테스트의 경우 MCPAY_TEST_DATABASE_URL을 일회용 마이그레이션된 데이터베이스를 가리키도록 설정하세요. 테스트는 애플리케이션 테이블을 비웁니다. 프로덕션 데이터베이스는 절대 사용하지 마세요.

루프백 인증 벤치마크를 실행하려면:

go run ./cmd/mcpay-benchmark --samples 1000 --warmup 100

이 벤치마크는 사용자 머신에서 원시, 로컬 SDK, 게이트웨이 p50/p95/p99을 보고합니다. 벤치마크는 세션 설정, 중앙 원장 쓰기, 비동기 사용량 업로드를 제외하므로 프로덕션 SLA가 아닙니다.

현재 제공되는 기능

MCPay는 테스트 크레딧을 사용한 통제된 베타에 적합합니다. 고객 자금을 보유할 준비는 되지 않았습니다.

저장소 구조

라이선스

MCPay는 Business Source License 1.1을 사용합니다. BSL은 OSI 승인 오픈소스 라이선스가 아니지만, 모든 사람에게 소스 접근 권한을 부여하고 복사, 수정, 재배포, 비프로덕션 사용을 허용합니다.

MCPay 추가 사용 허가(Additional Use Grant)는 사용자 또는 조직의 지난 12개월 동안 총 매출이 $100,000 USD 이하인 경우 내부 프로덕션 사용을 허용합니다. 제3자를 위한 호스팅, 관리형, 임베디드 또는 화이트라벨 MCPay 서비스는 허용하지 않습니다. 해당 허가 범위를 벗어난 프로덕션 사용은 상업용 라이선스가 필요합니다. 상업적 조건을 요청하려면 공식 저장소에 이슈를 개설하세요.

2030년 8월 13일에 이 버전은 Apache License 2.0으로 변경됩니다. BSL은 또한 버전의 첫 공개 BSL 배포 4주년이 더 먼저 도래하는 경우 해당 시점에 오픈소스 Change License를 적용합니다.

구속력 있는 조건은 LICENSE를 읽으세요. 대시보드는 apps/dashboard/LICENSE에서 MIT 라이선스에 따라 별도로 배포되며, 업스트림 작성자 및 MCPay 수정 사항에 대한 귀속 표시를 포함합니다. 실거래 출시 또는 펀드레이징 실사 전에 BSL 매개변수를 법무 자문에게 검토받으세요.

보안 연구는 환영합니다. 소스 접근으로 검토가 가능하지만 취약점이 없음을 증명하지는 않으며, BSL은 보안 보증 없이 소프트웨어를 제공합니다.