tgpay cryptoAPI
Telegram으로 문의하기
crypto-paymcpaiagent

AI 에이전트 연결하기

읽는 데 5분마지막 수정 2026년 11월 2일

원격 MCP 서버를 지원하는 AI 코딩 에이전트를 https://app.tgpaycrypto.com/mcp에 연결하세요. API 문서를 읽고 가맹점 앱 생성을 요청하며 웹훅 설정과 연동 코드 작성을 도울 수 있어요. 봇에서 앱 생성을 승인하면 직접 복사하지 않아도 에이전트가 권한 제한 토큰을 받아요. 실제 결제를 받기 전에 완성된 연동을 검토하고 테스트하세요.

이 주소는 MCP 서버예요(Model Context Protocol — 서비스를 AI 에이전트에 연결하는 표준이에요). 브라우저로 열면 설정 방법을 스스로 알려 줘요.

연결하기

쓰는 도구에 맞는 줄을 골라 주세요.

  • 원격 MCP를 지원하는 에이전트 — 이 프롬프트를 그대로 붙여 넣어요.

    Connect the tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay Crypto Merchant API.

    앱에서는 더보기 → Merchant API → AI 에이전트 연결에 복사하기 좋게 놓여 있어요.

  • Claude Code — claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp

  • claude.ai와 Claude Desktop — Claude 설정 안내에 따라 URL을 맞춤 커넥터로 추가하세요.

  • ChatGPT와 다른 MCP 클라이언트 — 계정과 워크스페이스에서 허용한다면 URL을 맞춤 MCP 서버로 추가하세요. ChatGPT는 현재 설정 안내를 따르세요.

먼저 테스트넷에서 연동하려면 https://testnet.tgpaycrypto.com/mcp를 사용하세요. 승인 링크는 @tgpaycrypto_testnet_bot을 열고 API 문서는 테스트넷 기본 URL을 사용해요.

API 토큰을 미리 만들 필요는 없어요. 다음 단계에서 에이전트가 자기 토큰을 받아요. 앱을 이미 직접 만들었다면 에이전트에게 필요한 권한만 담은 권한 제한 토큰을 만들어 연동에 사용하세요. 기본 토큰은 서버에 보관해 주세요. 어떤 토큰을 쓰더라도 MCP 서버를 통해서는 결제를 받는 것만 가능해요(아래 참고).

이 토큰을 MCP 서버에 전달하려면 클라이언트 연결 설정에서 서버를 추가하고 TgPayCrypto-API-Token: <token> 또는 Authorization: Bearer <token> 헤더를 지정하세요. 이 경우 승인 단계는 필요 없어요. 모든 클라이언트에 사용자 지정 헤더 입력란이 있는 건 아니에요(claude.ai와 ChatGPT 커넥터에는 없고, 서버는 OAuth 로그인을 지원하지 않아요). 그런 클라이언트에서는 아래 승인 절차를 쓰세요. 에이전트가 개별 도구 호출의 api_token 인수로 토큰을 전달할 수도 있는데, 도구에 선언되지 않은 인수를 클라이언트가 보낼 수 있을 때만 가능해요.

앱 승인하기

  1. 에이전트에게 결제를 붙여 달라고 하세요. 문서를 읽고 승인을 요청해요.

  2. 에이전트가 t.me 링크를 줘요. 열면 봇이 무엇을 요청하는지 보여 줘요. ✅ 앱 만들고 토큰 발급을 누르세요.

  3. 에이전트로 돌아가 토큰을 가져오고 연동을 계속하게 하세요.

앱과 에이전트의 토큰은 버튼을 누른 뒤 에이전트가 요청을 다시 확인할 때 만들어져요. 보통 몇 초면 돼요. 요청은 에이전트가 만든 때부터 10분 동안 유효해요. 에이전트가 그 안에 확인하지 않으면 봇이 이미 승인을 확인했더라도 아무것도 만들어지지 않고, 에이전트가 처음부터 다시 해야 해요. 앱 생성에는 계정 자격 조건이 적용돼요. 본인 인증이 필요하면 에이전트가 그 확인 단계에서 오류를 받으니, 인증을 마친 뒤 같은 10분 안에 에이전트에게 다시 확인하게 하거나 처음부터 다시 시작하게 하세요.

요청을 승인하면 새로 만들어지는 앱에 대해 Merchant API 이용약관에 동의하게 돼요. Mini App에서 직접 앱을 만들 때와 같아요.

링크는 언제나 내 에이전트에서 와요. 봇이 먼저 보내는 일은 없어요. 링크를 열기 전까지는 봇도 에이전트의 요청이 누구의 계정에 대한 것인지 몰라요. 버튼을 누르기 전에는 링크를 다시 열어도 같은 요청이 보여요. ✅ 앱 만들고 토큰 발급이나 ❌ 거절을 누르거나 10분이 지나면 링크는 더 이상 동작하지 않아요. 누르기 전에 링크가 만료되면 에이전트에게 처음부터 다시 해 달라고 하세요. 승인하기 전에는 아무것도 만들어지지 않아요.

❌ 거절을 눌러도 마찬가지로 아무것도 만들어지지 않고, 그 요청은 거기서 끝나요. 마음이 바뀌면 에이전트에게 새로 요청하게 하면 돼요.

⚠️ 내가 시작한 요청만 승인하세요

연결 요청은 내 계정에 앱을 만들겠다는 요청이에요. 방금 내 에이전트에게 결제를 붙여 달라고 했을 때만 승인하세요. 채팅이나 전달된 메시지, 모르는 사람의 “고객센터”처럼 다른 경로로 링크가 왔다면 거절하세요.

MCP 서버에서는 어떤 토큰으로도 송금, 송금 링크 만들기, 환불을 할 수 없어요. 이 승인 절차로 발급한 토큰도 마찬가지예요(아래 참고). 내가 요청하지 않은 앱은 만들지 마세요.

에이전트가 할 수 있는 일과 못 하는 일

위 승인 절차로 발급되는 토큰은 권한 제한 토큰이에요.

  • 할 수 있는 일 — 청구서 만들기와 삭제, 구독 플랜 만들기와 보관, 구독자의 구독 취소, 잔액과 시세, 통계 읽기, 웹훅 주소와 앱 이름 바꾸기.

  • 못 하는 일 — 송금, 송금 링크 만들기, 환불. 이 토큰에는 payouts, checks, refunds 권한이 없어요.

MCP 서버 자체에도 제한이 있어요. 앱 잔액에서 돈을 보내는 도구인 transfer, transferBatch, createCheck, refundInvoice는 현재 꺼져 있어요. 에이전트에게 보이지 않고, 전체 권한이 있는 기본 토큰으로 호출해도 거절돼요. 그래서 에이전트 토큰이 유출되거나 에이전트가 읽는 글에 악의적인 지시가 숨어 있어도 MCP를 통해 앱에서 돈을 보낼 수 없어요. 결제자가 남긴 메모에 그런 지시가 있는 경우도 마찬가지예요.

송금, 송금 링크 만들기, 환불은 여전히 API로 직접 할 수 있어요. 서버 코드에서 /pay/api를 호출할 때 작업에 맞는 payouts, checks, refunds 권한이 있는 토큰을 사용하세요. 앱에서 지급하려면 더보기 → Merchant API를 열고 앱을 선택한 다음 지급으로 들어가세요.

이 토큰도 비밀로 보관해 주세요. 청구서, 구독 플랜, 구독, 웹훅 주소, 앱 이름을 바꿀 수 있는 권한은 있어요. 에이전트에게 토큰이 발급될 때마다, 그리고 앱의 웹훅 주소가 바뀔 때마다 봇이 알려 드려요.

에이전트 토큰의 권한을 확인하거나 폐기하려면 더보기 → Merchant API에서 앱을 고르고 접근 권한과 토큰을 열어 권한 제한 토큰을 보세요. 폐기를 누르면 그 자리에서 못 쓰게 돼요. 앱과 잔액, 결제 내역은 그대로 남아요. 토큰 값은 다시 볼 수 없어요. 만료일이 있는 토큰은 만료되면 사용할 수 없어요.

웹훅 서명에는 기본 토큰이 필요해요

에이전트가 웹훅 주소를 내 서버로 맞춰 줄 수는 있어도, 거기 도착한 걸 검증해 줄 수는 없어요. 전송은 앱의 기본 토큰으로 서명되는데, 그 토큰은 에이전트가 볼 수 없거든요. 에이전트가 검증 코드를 작성하면 토큰을 직접 넣을 수 있도록 TGPAY_WEBHOOK_TOKEN 같은 환경 변수를 남겨 둬야 해요.

채워 넣으려면 더보기 → Merchant API를 열고 에이전트가 만든 앱을 찾아 접근 권한과 토큰에서 토큰 새로 발급을 누른 다음 보이는 값을 복사하세요. 한 번만 보여 줘요. 서버의 환경 변수에 넣고, 에이전트 설정이나 저장소에는 넣지 마세요. 새로 발급해도 에이전트의 권한 제한 토큰은 그대로라서 연동은 계속 돌아가요. 재발급은 PIN 또는 Face ID로 확인하세요. 에이전트가 만든 앱은 PIN이 없는 계정에 속할 수도 있지만, 토큰 재발급에는 활성화된 PIN이 필요해요. 먼저 보안에서 PIN을 설정하고 활성화될 때까지 기다려 주세요.

새로 발급하는 순간 서명이 새 토큰으로 바뀌어요. 그러니 첫 결제를 받은 뒤가 아니라, 서비스를 열기 전에 미리 해 두세요.

다음 글

함께 보면 좋은 문서

Merchant API (개발자용)개발자로 시작하기Merchant API (개발자용)Merchant API란?Merchant API (개발자용)API 레퍼런스: 웹훅