MCP 및 AI 에이전트

AI 에이전트에서 사용하기#

Claude Code나 Cursor 채팅에서 어시스턴트가 미디어를 만들게 하려면 MCP 서버를 사용하세요. 에이전트가 API 연동 코드를 작성한다면 Agent Skill을 사용하세요. 둘 다 함께 사용할 수 있으며, Skill에는 MCP가 연결된 경우 에이전트가 해당 도구를 우선 사용하도록 안내되어 있습니다.

서버 URL 및 로그인#

• 전송 방식: Streamable HTTP, 상태 비저장 방식입니다. 2025 및 2026-07-28 MCP 프로토콜 버전 클라이언트에서 작동합니다.
• 로그인: OAuth 2.1을 사용하며 MCP 인증 사양을 따릅니다. 클라이언트가 처음 연결되면 브라우저에서 CheaperGen 페이지가 열립니다. 로그인한 뒤 앱을 승인하세요. 승인된 앱은 대시보드 → API 키 → 연결된 앱에서 확인할 수 있고 언제든 연결을 해제할 수 있습니다.
• 헤드리스 및 CI: API 키로 인증하세요. 키는 Authorization: Bearer cg_live_… 형식으로 전송하면 됩니다. 자세한 내용은 API 키 사용에서 확인하세요.

클라이언트 연결하기#

Claude (claude.ai 및 Claude Desktop)#

1. Customize → Connectors 메뉴에서 사용자 지정 커넥터를 추가하세요.
2. 이름을 CheaperGen으로 지정하고 위 URL을 붙여넣은 뒤 추가 버튼을 선택하세요.
3. 연결을 선택하고 CheaperGen에 로그인해 승인하세요. 그런 다음 채팅의 도구 메뉴에서 커넥터를 활성화하세요.

Team 및 Enterprise 요금제에서는 조직의 소유자가 먼저 커넥터를 추가해야 할 수 있습니다. claude.ai에서 추가한 커넥터는 Claude Desktop에도 표시됩니다.

Claude Code#

claude mcp add --transport http cheapergen https://cheapergen.com/api/mcp

그다음 /mcp 명령을 실행하고 cheapergen 서버를 선택한 뒤 인증 버튼을 누르세요(또는 터미널에서 claude mcp login cheapergen을 실행하세요). 브라우저가 열리면 로그인하고 승인을 완료하세요. 모든 프로젝트에서 사용하려면 --scope user 옵션을 추가하세요. 플러그인을 설치하면 서버와 Agent Skill도 한 번에 추가됩니다:

/plugin marketplace add CheaperGen/skills
/plugin install cheapergen@cheapergen

ChatGPT#

데스크톱 앱(macOS 및 Windows). Work 또는 Codex 모드에서 ChatGPT 데스크톱 앱은 Codex CLI과 같은 MCP 설정을 사용하므로 codex mcp add로도 연결할 수 있습니다. 앱에서 직접 추가할 수도 있습니다:

1. Settings → MCP servers → Add server을 여세요.
2. 이름을 cheapergen으로 지정하고 Streamable HTTP를 선택한 뒤 위 URL을 붙여넣고 저장하세요.
3. 저장한 뒤 다시 시작 버튼을 누르세요. 이어서 인증 버튼을 선택하고 브라우저에서 CheaperGen에 로그인해 승인을 완료하세요. 작성창에 /mcp을 입력하면 연결을 확인할 수 있습니다.

chatgpt.com. 사용자 지정 MCP 서버는 플러그인으로 추가할 수 있습니다. ChatGPT Business, Enterprise, Edu 워크스페이스에서 사용할 수 있으며(Business에서는 관리자와 소유자가 추가해야 합니다). 모바일 앱이 아닌 웹에서 추가하세요:

1. Plugins → + → Add custom MCP server을 여세요.
2. 이름을 CheaperGen으로 지정하고 위 URL을 붙여넣은 뒤 OAuth을 인증 방식으로 선택하세요.
3. ‘이해했으며 계속 진행’에 체크하고 ‘플러그인으로 만들기’를 선택한 뒤 설치하고 로그인해 앱을 승인하세요.
4. 채팅 입력창에서 @ 기호를 입력한 뒤 플러그인을 선택하세요. ChatGPT는 generate 또는 add_credits 도구를 실행하기 전에 확인을 요청합니다.

Codex#

codex mcp add cheapergen --url https://cheapergen.com/api/mcp

이 설정은 서버를 ~/.codex/config.toml에 추가하고 브라우저에서 즉시 로그인을 엽니다. 건너뛰었나요? codex mcp login cheapergen을 실행하세요. Codex CLI, Codex IDE 확장 (톱니바퀴 메뉴 → MCP 서버), ChatGPT 데스크톱 앱이 모두 이 파일을 사용하므로 한 번만 설정하면 됩니다. Codex 클라우드 작업은 이 파일을 읽지 않습니다. 파일을 직접 편집하려면:

[mcp_servers.cheapergen]
url = "https://cheapergen.com/api/mcp"

Cursor#

~/.cursor/mcp.json (모든 프로젝트) 또는 .cursor/mcp.json (현재 프로젝트)에 추가하세요. 그런 다음 Customize → MCPs를 열고 cheapergen을 연결하세요. Cursor CLI에서는 cursor-agent mcp enable cheapergen를 실행한 뒤 cursor-agent mcp login cheapergen를 선택하세요.

{
  "mcpServers": {
    "cheapergen": {
      "url": "https://cheapergen.com/api/mcp"
    }
  }
}

VS Code (GitHub Copilot)#

.vscode/mcp.json에 추가하거나 MCP: 서버 추가…을 실행하고 HTTP를 선택하세요. 서버를 처음 시작할 때 VS Code에서 로그인을 요청합니다. 이후 Copilot Chat의 에이전트 모드에서 도구를 사용하세요.

{
  "servers": {
    "cheapergen": {
      "type": "http",
      "url": "https://cheapergen.com/api/mcp"
    }
  }
}

기타 클라이언트#

원격 서버 및 OAuth만 지원하는 클라이언트는 URL만 있으면 됩니다 (일부는 "url" 대신 "serverUrl"을 사용). 로컬 (stdio) 서버만 실행할 수 있는 클라이언트는 mcp-remote 브리지를 사용할 수 있습니다. Node.js가 필요하며 로그인 절차를 처리합니다.

{
  "mcpServers": {
    "cheapergen": {
      "type": "http",
      "url": "https://cheapergen.com/api/mcp"
    }
  }
}

{
  "mcpServers": {
    "cheapergen": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://cheapergen.com/api/mcp"
      ]
    }
  }
}

API 키 사용(헤드리스, CI)#

브라우저로 로그인할 수 없는 경우 대시보드 → API 키의 API 키를 보내세요. 에이전트마다 키를 따로 만들어 개별 해지할 수 있게 하세요. 아래처럼 환경 변수에 보관하세요. 작은따옴표는 키가 아닌 변수 이름을 감싸며 연결할 때 클라이언트가 그 값을 읽습니다. Claude Code는 커밋된 .mcp.json에서 ${CHEAPERGEN_API_KEY}도 각 개발자의 환경 변수로 확장합니다.

claude mcp add --transport http cheapergen https://cheapergen.com/api/mcp \
  --header 'Authorization: Bearer ${CHEAPERGEN_API_KEY}'

codex mcp add cheapergen --url https://cheapergen.com/api/mcp \
  --bearer-token-env-var CHEAPERGEN_API_KEY

gemini mcp add --transport http cheapergen https://cheapergen.com/api/mcp \
  -H 'Authorization: Bearer ${CHEAPERGEN_API_KEY}'

{
  "mcpServers": {
    "cheapergen": {
      "type": "http",
      "url": "https://cheapergen.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${CHEAPERGEN_API_KEY}"
      }
    }
  }
}

npx @modelcontextprotocol/inspector --cli https://cheapergen.com/api/mcp --transport http \
  --header "Authorization: Bearer $CHEAPERGEN_API_KEY" --method tools/list

도구#

모든 도구는 REST API와 같은 코드 (API 레퍼런스)를 사용하므로 가격, 검증, 오류도 동일합니다. 결과는 간결한 JSON으로 반환됩니다. 완성된 이미지는 작은 인라인 미리보기로도 제공되어 채팅에 바로 표시되고 에이전트가 결과를 확인할 수 있으며, 모든 출력 파일은 리소스 링크로 제공되어 표시하거나 다운로드할 수 있습니다.

이미지는 대개 generate 호출 한 번이면 완료됩니다. 동영상은 1~수 분이 걸리므로 에이전트가 작업을 제출한 뒤 완료될 때까지 get_generation 호출에 wait_seconds 값을 넣어 반복해서 조회합니다. generate 작업이 완료되면 다음을 반환합니다:

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "status": "succeeded",
  "endpoint": "bytedance/seedream-5.0-lite/text-to-image",
  "outputs": [
    "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.png"
  ],
  "cost": {
    "amount_usd": 0.0303,
    "official_usd": 0.035,
    "list_price_source": "official",
    "list_price_label": "공식 가격",
    "saved_usd": 0.0047,
    "final": true
  },
  "created_at": "2026-10-16T09:12:43.545Z",
  "completed_at": "2026-10-16T09:12:49.058Z",
  "outputs_expire_at": "2026-10-17T09:12:49.058Z",
  "next": "완료되었습니다. 출력 URL을 표시하거나 다운로드하세요. outputs_expire_at 이전에 저장해야 합니다."
}

프롬프트 예시#

• “참조 동영상을 지원하는 CheaperGen 동영상 모델은 무엇이며, 각 모델에서 720p로 5초를 만들면 비용이 얼마인가요?”
• “Seedance 2.0 Fast로 종이배가 비 내리는 네온 거리 위를 떠내려가는 5초짜리 720p 영상을 만들어 줘. 카메라가 천천히 앞으로 다가가게 해 줘. 먼저 가격을 알려줘.”
• “Seedream 5.0 Lite로 이 머그잔의 제품 사진을 네 장 만들어 줘. 각 사진은 $0.05 미만으로 해 줘: https://example.com/mug.png”
• “이 사진을 Wan 3.0으로 6초 세로 영상으로 만들어 줘: https://example.com/portrait.jpg”
• “바탕화면에 있는 사진(~/Desktop/beach.jpg)을 Kling 3.0으로 5초 영상으로 만들어 줘. 먼저 가격을 알려 줘.”
• “Seedance 2.0으로 참조 동영상을 만들어 줘. @Image1은 인물, @Image2는 거리야. @Video1처럼 카메라를 움직여 줘. URL은 다음과 같아: …”
• “현재 CheaperGen 잔액이 얼마이고, Seedance 2.0으로 1080p 10초 영상을 몇 개 만들 수 있나요?”

Agent Skill#

CheaperGen은 Agent Skills 형식의 단일 SKILL.md 파일입니다. 모델 선택, 스키마 확인, 견적·제출, 폴링 또는 웹훅 확인, 참조 멘션과 업로드, 요금 및 오류 처리까지 전체 작업 흐름을 에이전트에 안내합니다. 필요한 작업이 있을 때만 불러옵니다. REST 요청 시 CHEAPERGEN_API_KEY 환경 변수에서 API 키를 읽으며, MCP 도구가 연결되어 있으면 이를 우선 사용합니다. 원본은 github.com/CheaperGen/skills에서 확인할 수 있습니다.

/plugin marketplace add CheaperGen/skills
/plugin install cheapergen@cheapergen

npx skills add CheaperGen/skills

mkdir -p ~/.claude/skills/cheapergen
curl -fsSL https://cheapergen.com/skills/cheapergen/SKILL.md -o ~/.claude/skills/cheapergen/SKILL.md

mkdir -p .claude/skills/cheapergen
curl -fsSL https://cheapergen.com/skills/cheapergen/SKILL.md -o .claude/skills/cheapergen/SKILL.md

Skills CLI로 Claude Code, Cursor, Codex, Gemini CLI 등 에이전트에 설치할 수 있습니다. -a 옵션은 하나의 에이전트에, -g 옵션은 모든 프로젝트에 설치합니다. Claude 앱에서는 cheapergen 폴더를 압축해 사용자 지정 스킬로 업로드하세요.

요청 제한 및 결제#

• 요청 제한은 연결된 앱 또는 API 키마다 REST API와 동일하게 적용됩니다(MCP 요청도 각각 한 번씩 한도에 포함). 계정별 동시 진행 생성 한도도 동일합니다.
• 생성 작업이 generate 도구를 통해 제출되면 요금이 잔액에서 보류되고, 실패하거나 취소되면 전액 환불됩니다. 자세한 내용: 결제 및 크레딧.
• MCP로 만든 생성은 대시보드와 GET /api/v1/generations 응답에 표시되며 출처는 source: "mcp"입니다.
• 로그인 토큰은 1시간 동안 유효하며 클라이언트가 자동으로 갱신합니다. 대시보드에서 앱 연결을 해제하면 접근 권한이 즉시 사라집니다.
• 결과 URL은 공개 링크이며 API 데이터 보관 기간(기본값 1일)이 지나면 만료됩니다. 보관할 항목은 다운로드하세요.

문제 해결#

• 클라이언트에 서버 인증이 필요하다고 표시됩니다: 로그인 절차를 마무리하세요(Claude Code에서는 /mcp → cheapergen → Authenticate). 앱 연결을 해제했거나 90일 동안 사용하지 않았다면 다시 로그인하세요.
• 로그인 페이지에 앱이 등록되지 않았거나 리디렉션 주소가 일치하지 않는다고 표시됩니다: 클라이언트에서 MCP 서버를 제거하고 다시 추가해 클라이언트가 새로 등록하도록 하세요.
• 도구 호출 시간이 초과됩니다: wait_seconds 값을 낮추세요. 생성 작업은 계속 실행되므로 나중에 get_generation로 결과를 가져오세요.
• invalid_request: 입력값이 엔드포인트 스키마와 맞지 않습니다. 오류의 param에 필드가 표시됩니다. 에이전트에 먼저 get_model을 호출하도록 하세요.