가이드

레시피: 유료 MCP 서버

MCP 서버 도구에 호출마다 크레딧으로 요금을 받으세요. 사람이 패키지를 한 번 사고, 호출마다 먼저 차감한 뒤 작업합니다.

에이전트가 직접 결제할 필요는 없습니다. 사람이 브라우저에서 크레딧 패키지를 사고, 이후 도구 호출마다 잔액을 확인하고, 멱등성 키로 크레딧을 차감한 뒤 작업합니다. 크레딧이 없으면 도구가 충전 링크로 답하고, 에이전트가 그 링크를 사람에게 보여 줍니다. x402도, 에이전트 안의 지갑도, 자동 청구도 없습니다.

어시스턴트와 함께: 이 레시피는 Perly Pay 플러그인의 paid-mcp-tools 스킬이 내 프로젝트에서 실행합니다. 실행 가능한 예제는 플러그인 저장소의 examples/paid-mcp-server(MIT)입니다.

작동 방식

1
크레딧 패키지
API 크레딧과 같습니다. 도구마다 가격을 정하고 설명에 적으세요.
2
호출하는 쪽
호스팅된 서버가 구독자마다 API 키를 고객의 external_id에 연결합니다. PERLY_PAY_SECRET_KEY는 내 서버에만 있습니다.
3
먼저 차감, 그다음 작업
도구 이름을 action으로, 내 서버가 호출마다 만든 새 키로 credits.consume, 그다음 작업.
4
부족하면?
프로토콜 오류가 아니라 isError: true와 충전 링크가 담긴 도구 결과를 돌려주세요: 클라이언트가 그걸 보여 줍니다.
5
무료 도우미
에이전트가 상황을 설명할 수 있게 balance와 top_up 도구.

A paid tool

server.registerTool("summarize", { description: "Costs 3 credits.", inputSchema: { text: z.string() } }, async ({ text }, extra) => {
  const refused = await charge(userId, 3, "summarize", extra.requestId); // credits.consume, or a top-up message
  if (refused) return { isError: true, content: [{ type: "text", text: refused }] };
  return { content: [{ type: "text", text: summarize(text) }] };
});

예제 실행

1
설치
examples/paid-mcp-server에서 npm install(Node 20.12+).
2
키
.env.example을 .env로 복사하고 PERLY_PAY_SECRET_KEY에 테스트 키(sk_test_…)를 넣으세요.
3
준비
npm run setup이 내 키로 상품과 가격을 만들고 .env용 ID를 출력합니다.
4
실행
README에 적힌 대로 npm start(또는 npm run dev).
5
지갑 없이 결제
Claude Code에 추가하고(claude mcp add paid-tools -- npx tsx "$PWD/src/server.ts") word_stats를 실행하세요: 답은 충전 페이지입니다. 패키지를 골라 Simulate payment를 누르고 다시 실행하세요.

함정

다른 사람이 복사하는 MCP 설정에 PERLY_PAY_SECRET_KEY. 서버를 직접 호스팅하거나 내 백엔드를 부르게 하세요.
작업 뒤에 차감: 차감이 실패하면 무료로 일한 셈입니다.
JSON-RPC ID로 만든 차감 키: 클라이언트가 고르는 값이라, 같은 ID면 첫 차감이 돌아오고 도구가 또 무료로 일합니다.