메인 콘텐츠로 건너뛰기

개요

모델 컨텍스트 프로토콜(MCP)은 AI 애플리케이션이 외부 데이터 소스 및 API에 안전하게 연결할 수 있도록 하는 개방형 표준입니다. Dodo Payments MCP 서버는 Claude, Cursor 및 기타 MCP 호환 클라이언트와 같은 AI 어시스턴트에게 귀하의 결제 인프라에 대한 구조화된 접근을 제공합니다. Dodo Payments MCP 서버는 Stainless로 구축되었으며, Code Mode 아키텍처를 사용하여 AI 에이전트가 Dodo Payments SDK에 대해 TypeScript 코드를 작성하고 실행할 수 있는 격리된 샌드박스 환경을 제공합니다.

주요 기능

  • 결제 작업: 결제 및 환불 생성, 검색 및 관리
  • 구독 관리: 반복 청구, 업그레이드 및 취소 처리
  • 고객 관리: 고객 데이터 및 포털 접근 관리
  • 제품 카탈로그: 제품, 가격 및 할인 생성 및 업데이트
  • 라이선스 관리: 소프트웨어 라이선스 활성화, 검증 및 관리
  • 사용 기반 청구: 측정된 사용량 추적 및 청구

Code Mode 작동 방식

Dodo Payments MCP 서버는 Code Mode를 사용하여 AI 에이전트에 두 가지 강력한 도구를 제공합니다:
  1. 문서 검색 도구: Dodo Payments API 및 SDK에 대한 문서를 쿼리하여 사용 가능한 작업 및 매개변수를 이해합니다.
  2. 코드 실행 도구: 웹 또는 파일 시스템 접근 없이 안전한 샌드박스 환경에서 SDK에 대해 TypeScript 코드를 작성하고 실행합니다.
이 아키텍처는 AI 에이전트가 복잡하고 다단계 결제 작업을 결정론적으로 반복적으로 수행할 수 있게 합니다.
Code Mode를 사용하면 에이전트가 여러 API 호출을 연결하고 조건 논리를 처리하며 계산을 수행할 수 있습니다. 모든 작업이 단일 도구 호출 내에서 이루어집니다.

설치

작업 흐름에 가장 적합한 설치 방법을 선택하세요.

원격 MCP 서버 (권장)

로컬 설정이나 설치 없이 호스팅된 MCP 서버에 접근합니다. 시작하는 가장 빠른 방법입니다.
1

원격 서버에 접근하기

브라우저에서 https://mcp.dodopayments.com으로 이동합니다.
2

MCP 클라이언트 구성하기

특정 클라이언트에 대한 제공된 JSON 구성을 복사합니다. Cursor 또는 Claude Desktop의 경우, 이를 MCP 설정에 추가하세요:
{
  "mcpServers": {
    "dodopayments_api": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
    }
  }
}
3

인증 및 구성

OAuth 흐름이 다음을 요청합니다:
  • Dodo Payments API 키 입력
  • 환경 선택 (테스트 또는 라이브)
  • MCP 클라이언트 유형 선택
API 키를 안전하게 보관하세요. 개발 중에는 테스트 모드 키를 사용하세요.
4

설정 완료

로그인 및 승인을 클릭하여 연결을 승인합니다.
연결되면 AI 어시스턴트가 Dodo Payments API와 상호작용할 수 있습니다.

NPM 패키지

NPM을 사용하여 로컬에서 MCP 서버를 설치하고 실행합니다.
# Set your environment variables
export DODO_PAYMENTS_API_KEY="dodo_test_..."
export DODO_PAYMENTS_WEBHOOK_KEY="your_webhook_key"
export DODO_PAYMENTS_ENVIRONMENT="live_mode"

# Run the latest version
npx -y dodopayments-mcp@latest
@latest를 사용하여 항상 최신 버전을 가져오거나, 안정성을 위해 @1.0.0와 같은 특정 버전에 고정하세요.

Docker

일관된 배포를 위해 컨테이너화된 환경에서 MCP 서버를 실행합니다.
# Pull the latest image
docker pull ghcr.io/dodopayments/mcp:latest

# Run the container
docker run -e DODO_PAYMENTS_API_KEY="dodo_test_..." \
  -e DODO_PAYMENTS_WEBHOOK_KEY="your_webhook_key" \
  -e DODO_PAYMENTS_ENVIRONMENT="live_mode" \
  ghcr.io/dodopayments/mcp:latest
Docker 이미지는 GitHub Container Registry에서 사용할 수 있습니다.

클라이언트 구성

선호하는 AI 클라이언트에서 Dodo Payments MCP 서버를 구성합니다.
Cursor에서 Dodo Payments MCP 서버를 설정하여 결제 데이터에 대한 대화형 접근을 가능하게 합니다.원클릭 설치아래 버튼을 사용하여 Cursor에 MCP 서버를 직접 설치하세요:[Cursor에 추가](https://cursor.com/en-US/install-mcp?name=dodopayments-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImRvZG9wYXltZW50cy1tY3AiXSwiZW52Ijp7IkRPRE9fUEFZTUVOVFNfQVBJX0tFWSI6IlNldCB5b3VyIERPRE9fUEFZTUVOVFNfQVBJX0tFWSBoZXJlLiIsIkRPRE9fUEFZTUVOVFNfV0VCSE9PS19LRVkiOiJTZXQgeW91ciBET0RPX1BBWU1FTlRTX1dFQkhPT0tfS0VZIGhlcmUuIn19)클릭 후, Cursor의 mcp.json에서 환경 변수를 설정하세요. Cursor 설정 > 도구 및 MCP > 새 MCP 서버를 통해 설정합니다.수동 구성
1

Cursor 설정 열기

Cursor 설정 > 기능 > 모델 컨텍스트 프로토콜로 이동하거나 Cmd/Ctrl + Shift + P를 눌러 “MCP 설정”을 검색합니다.
2

구성 편집

구성 편집을 클릭하여 mcp_config.json 파일을 엽니다.
3

Dodo Payments 구성 추가

다음 구성 중 하나를 선택하세요:원격 서버 (권장)
{
  "mcpServers": {
    "dodopayments": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
    }
  }
}
로컬 NPX
{
  "mcpServers": {
    "dodopayments": {
      "command": "npx",
      "args": ["-y", "dodopayments-mcp@latest"],
      "env": {
        "DODO_PAYMENTS_API_KEY": "dodo_test_...",
        "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key"
      }
    }
  }
}
4

저장 및 재시작

구성 파일을 저장하고 Cursor를 재시작합니다.
AI 어시스턴트에게 Dodo Payments 데이터에 대해 질문하여 연결을 확인합니다.

환경 변수

환경 변수를 사용하여 MCP 서버 동작을 구성합니다.
변수설명필수
DODO_PAYMENTS_API_KEYDodo Payments API 키
DODO_PAYMENTS_WEBHOOK_KEY웹훅 서명 키아니요
DODO_PAYMENTS_ENVIRONMENT프로덕션을 위해 live_mode로 설정아니요

원격 실행

웹 기반 클라이언트 또는 에이전트 워크플로우를 위해 MCP 서버를 원격 HTTP 서버로 배포합니다.
# Start as remote server
npx -y dodopayments-mcp --transport=http

# Specify a custom port
npx -y dodopayments-mcp --transport=http --port=3000

원격 서버 구성

배포 후, 클라이언트는 서버 URL을 사용하여 연결할 수 있습니다:
{
  "mcpServers": {
    "dodopayments_api": {
      "url": "http://localhost:3000",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    }
  }
}

인증 헤더

원격 서버는 다음 헤더를 통해 인증을 수락합니다:
헤더설명
AuthorizationBearer 토큰 인증
x-dodo-payments-api-key직접 API 키 헤더

클라이언트 기능

다양한 MCP 클라이언트는 MCP 사양에 대한 지원 수준이 다릅니다. 서버는 이러한 제한을 우회하기 위해 도구 스키마를 자동으로 조정할 수 있습니다.
# Auto-detect client (default)
npx dodopayments-mcp --client=infer

# Configure for specific clients
npx dodopayments-mcp --client=cursor
npx dodopayments-mcp --client=claude
npx dodopayments-mcp --client=claude-code
npx dodopayments-mcp --client=openai-agents

사용 가능한 클라이언트 프리셋

클라이언트설명
infer클라이언트 자동 감지 (기본값)
cursorCursor 편집기
claudeClaude AI 웹 또는 데스크탑
claude-codeClaude Code CLI
openai-agentsOpenAI 에이전트 플랫폼

수동 기능 구성

위에 나열되지 않은 클라이언트의 경우, 기능을 수동으로 구성합니다:
# Disable $ref pointer support and set max tool name length
npx dodopayments-mcp --no-capability=refs --capability=tool-name-length=40
사용 가능한 기능:
  • top-level-unions - 최상위 유니온 타입 지원
  • valid-json - 올바른 JSON 문자열 인수 구문 분석
  • refs - 스키마에서 $ref 포인터 지원
  • unions - 유니온 타입 지원 (anyOf)
  • formats - 형식 유효성 검사 지원
  • tool-name-length=N - 최대 도구 이름 길이
npx dodopayments-mcp --describe-capabilities를 실행하여 자세한 기능 정보를 확인하세요.

도구 필터링

AI 어시스턴트에 노출되는 API 작업을 제어하여 성능을 최적화하고 보안을 유지합니다.

작업 유형별 필터링

읽기 전용 또는 쓰기 작업에 대한 접근을 제한합니다.
# Only expose read operations (GET requests)
npx dodopayments-mcp --operation=read

# Only expose write operations (POST, PUT, DELETE)
npx dodopayments-mcp --operation=write
개발 중에는 --operation=read를 사용하여 데이터의 우발적인 수정을 방지하세요.

리소스별 필터링

특정 API 리소스에 도구를 제한합니다.
# Only expose payment-related tools
npx dodopayments-mcp --resource=payments

# Expose multiple resources
npx dodopayments-mcp --resource=payments --resource=customers

# Use wildcards for resource groups
npx dodopayments-mcp --resource=subscription*

특정 도구 포함 또는 제외

사용 가능한 개별 도구를 세밀하게 조정합니다.
# Include only specific tools
npx dodopayments-mcp --tool=create_payments --tool=list_payments

# Exclude specific tools
npx dodopayments-mcp --no-tool=delete_products

# Disable the docs search tool
npx dodopayments-mcp --no-tools=docs

# List all available tools
npx dodopayments-mcp --list

필터 결합

정확한 제어를 위해 여러 필터를 동시에 적용합니다.
# Only payment and subscription read operations
npx dodopayments-mcp --operation=read --resource=payments --resource=subscriptions

URL 쿼리 매개변수 필터링 (원격 서버)

원격 서버를 사용할 때, URL 쿼리 매개변수를 통해 필터를 적용합니다:
https://mcp.dodopayments.com/?operation=read
https://mcp.dodopayments.com/?resource=payments

동적 도구 모드

대규모 API의 경우, 모든 도구를 한 번에 로드하면 AI의 컨텍스트 창이 압도될 수 있습니다. 동적 도구 모드는 보다 효율적인 대안을 제공합니다.
npx dodopayments-mcp --tools=dynamic
동적 모드에서는 세 가지 메타 도구가 개별 API 도구를 대체합니다:
  1. list_api_endpoints - 선택적 필터링과 함께 사용 가능한 메서드를 발견합니다.
  2. get_api_endpoint_schema - 특정 메서드에 대한 자세한 스키마를 가져옵니다.
  3. invoke_api_endpoint - 적절한 매개변수로 어떤 메서드든 실행합니다.
50개 이상의 메서드를 가진 API에 대해 동적 도구가 자동으로 활성화됩니다. 모든 도구를 포함하려면 --tools=all로 재정의하세요.
# Use both dynamic tools and specific resources
npx dodopayments-mcp --tools=dynamic --resource=payments

고급 사용법

프로그래밍적 통합

사용자 지정 MCP 서버를 구축하거나 기존 서버를 프로그래밍적으로 확장합니다.
import { server, endpoints, init } from "dodopayments-mcp/server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Initialize with all default endpoints
init({ server, endpoints });

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);

사용자 지정 도구 개발

자신의 도구와 비즈니스 로직으로 MCP 서버를 확장합니다.
import { server, init } from "dodopayments-mcp/server";
import createPayments from "dodopayments-mcp/tools/payments/create-payments";
import { zodToJsonSchema } from "zod-to-json-schema";
import { z } from "zod";

// Define a custom tool
const customTool = {
  tool: {
    name: 'calculate_payment_total',
    description: 'Calculate payment total with tax and fees',
    inputSchema: zodToJsonSchema(
      z.object({
        amount: z.number().describe('Base amount in cents'),
        tax_rate: z.number().describe('Tax rate as decimal'),
      })
    ),
  },
  handler: async (client, args) => {
    const total = args.amount * (1 + args.tax_rate);
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ total, currency: 'usd' }),
      }],
    };
  },
};

// Initialize with custom tools
init({ 
  server, 
  endpoints: [createPayments, customTool] 
});

보안 모범 사례

API 자격 증명을 보호하고 안전한 통합을 유지합니다.
자격 증명을 버전 관리에 커밋하지 마세요API 키를 환경 변수 또는 안전한 비밀 관리 시스템에 저장합니다.
# Use environment variables
export DODO_PAYMENTS_API_KEY="dodo_test_..."

# Use a .env file (add to .gitignore)
echo "DODO_PAYMENTS_API_KEY=dodo_test_..." > .env
정기적으로 키를 교체하세요정기적으로 새로운 API 키를 생성하고 Dodo Payments 대시보드를 통해 이전 키를 폐기합니다.개발 중에는 테스트 키를 사용하세요생산 데이터에 영향을 주지 않도록 항상 개발 중에는 테스트 모드 API 키를 사용하세요.
생산 환경에서 도구 필터링 적용AI 어시스턴트가 필요로 하는 작업만 노출되도록 제한합니다.
# Production: read-only access
npx dodopayments-mcp --operation=read

# Development: full access
npx dodopayments-mcp
원격 서버에 대한 인증 구현원격으로 배포할 때는 항상 Authorization 헤더 또는 x-dodo-payments-api-key 헤더를 통해 인증을 요구합니다.API 사용 모니터링Dodo Payments 대시보드를 통해 MCP 서버 활동을 추적하고 비정상적인 패턴에 대한 경고를 설정합니다.
원격 서버에 HTTPS 사용항상 HTTPS 엔드포인트 뒤에 원격 MCP 서버를 배포합니다.요율 제한 구현MCP 서버와 API 수준 모두에서 남용을 방지하기 위해 요율 제한을 구현합니다.네트워크 접근 제한어떤 클라이언트가 MCP 서버에 연결할 수 있는지를 제한하기 위해 방화벽 규칙을 구성합니다.

문제 해결

API 키 확인API 키가 올바르게 설정되어 있고 필요한 권한이 있는지 확인합니다.
# Test your API key
curl -H "Authorization: Bearer dodo_test_..." \
  https://api.dodopayments.com/payments
네트워크 연결 확인Dodo Payments API 엔드포인트에 도달할 수 있는지 확인합니다.클라이언트 로그 검토MCP 클라이언트에서 자세한 로깅을 활성화하여 연결 문제를 진단합니다.
API 키 환경 확인테스트 엔드포인트에는 테스트 키를, 프로덕션 엔드포인트에는 라이브 키를 사용하고 있는지 확인합니다.환경 변수 확인DODO_PAYMENTS_ENVIRONMENT가 올바르게 설정되었는지 확인합니다 (프로덕션의 경우 live_mode).자격 증명 재생성문제가 지속되면 대시보드를 통해 새로운 API 키를 생성합니다.
입력 매개변수 검증AI 어시스턴트가 각 도구에 대해 올바르게 형식화된 매개변수를 제공하고 있는지 확인합니다.오류 메시지 검토API의 오류 응답을 확인하여 무엇이 잘못되었는지에 대한 구체적인 지침을 확인합니다.API 직접 테스트curl 또는 Postman을 통해 Dodo Payments API를 직접 호출할 때 작업이 작동하는지 확인합니다.
다른 클라이언트 프리셋 시도도구가 제대로 작동하지 않으면 클라이언트를 명시적으로 지정해 보세요:
npx dodopayments-mcp --client=cursor
기능 지원 확인일부 클라이언트는 모든 JSON 스키마 기능을 지원하지 않습니다. --describe-capabilities를 사용하여 지원되는 내용을 이해하세요.

리소스