AI 에이전트와 카카오페이 결제 오픈 API 연동하기: MCP Agent Toolkit 개발기

요약: 이 글에서는 카카오페이가 AI 에이전트와 결제 API를 연동하기 위해 Model Context Protocol(MCP)을 도입하고, 멀티 프레임워크를 지원하는 MCP Agent Toolkit을 개발한 과정을 다룹니다. 기존 OpenAI function calling이나 LangChain tool 방식의 한계를 극복하기 위해 MCP를 선택했으며, 결제·정기결제 관련 총 8개의 Tool을 설계해 자연어로 처리할 수 있도록 구현했습니다. 또한 LangChain, OpenAI, Vercel AI SDK 등 다양한 환경과의 연동 예시와 챗봇 데모를 통해 실제 활용 방안을 제시하며, 표준화와 체계적 개발 접근이 중요하다는 걸 강조합니다.

💡 리뷰어 한줄평

ian.wizard AI시대를 맞아 카카오페이와 다양한 AI 에이전트들을 잇기 위한 많은 고민과 노력을 엿볼 수 있었습니다. MCP를 직접 개발할 때 어떤 것들을 고려해야 할지, 어떠한 구조로 가져가면 좋을지에 대해 궁금하시다면 이 글을 추천합니다.

snow.y 결제가 AI를 만나면 어떤 방향으로 진화할까요? 개발자에게는 더욱 쉬운 결제 연동을, 사용자에게는 더 친숙하고 편리한 결제 경험을 주기 위해 결제에 Model Context Protocol(MCP)을 도입한 구체적인 사례를 만나보세요.

시작하며

안녕하세요, 저는 카카오페이 결제기술파티에서 결제 코어 시스템을 개발하고 있는 리입니다. 최근 AI 에이전트 기술이 빠르게 발전하면서 “AI가 결제도 처리할 수 있을까?”라는 질문을 자주 받게 되었습니다.

특히 ChatGPT, Claude 등의 AI 모델이 function calling을 통해 외부 API를 호출할 수 있게 되면서, 결제 시스템과의 연동 가능성에 대한 관심이 높아졌습니다. 이러한 기술적 가능성을 실제 서비스로 구현하기 위해서는 체계적인 접근이 필요했습니다.

이번 글에서는 카카오페이에서 AI 에이전트와 결제 API를 효과적으로 연동하기 위해 Model Context Protocol(MCP)을 도입하고, 멀티 프레임워크를 지원하는 Agent Toolkit을 개발한 경험을 공유하고자 합니다.

왜 AI 에이전트와 결제 API 연동을 고민했는가?

AI 에이전트의 현실화

요즘의 AI는 빠르게 우리에게 다가오고 있습니다. 과거 특정 시기에 기술적으로 광풍이 불었지만 유의미한 형태로 현실 세계에 나오지 못했던 기술들과는 사뭇 다릅니다. 특히 function calling 기능이 등장하면서 AI가 단순히 대화만 하는 것이 아니라, 실제로 시스템을 조작할 수 있게 되었습니다.

개발자로서 하루가 다르게 새로운 뉴스가 나오는 AI 기술을 바라볼 때마다 놀라운 변화의 속도를 실감합니다. 이제는 “이 기술을 어떻게 하면 더 많은 개발자들이 쉽게 활용할 수 있을까?”, “결제 시스템과 AI를 어떻게 효과적으로 연결할 수 있을까?”라는 고민을 하게 되었습니다.

이러한 고민은 개인적인 호기심을 넘어 카카오페이 차원에서도 중요한 화두가 되었습니다. 이에 따라 LLM 기술의 빠른 발전과 가능성을 주의 깊게 살피며, 앞으로 더 많은 개발자들이 변화에 자연스럽게 적응하고 활용할 수 있도록 필요한 도구와 인프라를 차근차근 준비하려고 합니다.

글로벌 핀테크 트렌드

이러한 AI와 결제 시스템의 연동은 카카오페이만의 고민이 아닙니다. 글로벌 핀테크 업계에서도 AI 에이전트 기술을 적극적으로 도입하고 있습니다.

PayPal과 Stripe 같은 글로벌 핀테크 기업들은 이미 AI Agent Toolkit과 MCP Server를 출시하여 개발자들이 결제, 배송 추적, 반품 처리 등의 운영을 AI로 자동화할 수 있도록 지원하고 있습니다.

이처럼 글로벌 핀테크 기업들이 AI 연동에 적극 투자하는 이유는 명확합니다. AI를 통해 고객 지원 자동화, 개발자 경험 개선, 새로운 비즈니스 모델 창출이 가능해졌기 때문입니다.

MCP(Model Context Protocol) 도입 결정

기존 방식의 한계

처음에는 단순히 OpenAI의 function calling이나 LangChain의 tool 기능을 사용해서 결제 API를 연동하는 방법을 고민했습니다. 하지만 이런 방식에는 몇 가지 문제가 있었습니다:

프레임워크 종속성: 특정 AI 프레임워크에 의존하면 다른 도구와의 호환성 문제
확장성 한계: 새로운 AI 도구나 프레임워크가 등장할 때마다 별도 구현 필요

MCP 선택 이유

이러한 한계들을 해결하기 위해 MCP를 선택했습니다:

프레임워크 독립성: Claude, GPT 등 다양한 LLM을 지원하는 MCP 호스트(예: Claude Desktop, Cursor, Windsurf 등)에서 사용 가능
확장성: 새로운 도구나 프레임워크 추가가 용이

MCP와 Tool이란?

MCP(Model Context Protocol) 는 AI 모델과 외부 도구 간의 표준화된 통신 프로토콜입니다. 이를 통해 AI가 외부 시스템의 기능을 체계적이고 일관된 방식으로 사용할 수 있습니다.

MCP의 핵심은 AI가 실행할 수 있는 기능들을 ‘Tool’이라는 단위로 정의하고 관리하는 것입니다. 예를 들어, 결제 API를 호출하거나 데이터를 조회하는 각각의 기능이 하나의 Tool이 됩니다.

Tool은 MCP에서 AI가 호출할 수 있는 개별 기능을 의미합니다. 각 Tool은 다음과 같은 구조로 정의됩니다:

method: Tool을 식별하는 고유한 이름
name: 사람이 읽기 쉬운 Tool 이름
description: Tool의 기능 설명
parameters: Tool 실행에 필요한 입력값 정의 (Zod 스키마)
actions: Tool의 권한 및 사용 가능한 액션 정의
execution: 실제 기능을 수행하는 함수(내부적으로 MCP 서버에서 호출됨)

Tool 범위 결정 과정

MCP를 도입하기로 결정한 후, 가장 중요한 고민은 “어떤 Tool들을 지원할 것인가?”였습니다.

카카오페이 Open API에서 제공하는 주요 결제 API들을 모두 지원하기로 했습니다. 결제 준비부터 승인, 취소, 상태 조회까지의 기본적인 결제 플로우와 정기결제 관련 기능을 포함하여 총 8개의 Tool로 구성했습니다:

데모 결제: 개발 및 테스트용 데모 결제 링크 생성
결제 플로우: 결제 준비, 승인, 취소, 상태 조회
정기결제: 정기결제 요청, 상태 조회, 비활성화

예를 들어, 결제 상태 조회 Tool(get_payment)은 다음과 같이 정의되어 있습니다:

// getPayment.ts (일부)
export const getPaymentParameters = (_context: Context = {}): z.AnyZodObject =>
  z.object({
    tid: z.string().describe('결제 고유번호'),
  });

export const getPayment = async (
  client: KakaoPayClient,
  context: Context,
  params: z.infer<ReturnType<typeof getPaymentParameters>>,
) => {
  const response = await client.post(KAKAO_PAY_API_ENDPOINTS.PAYMENT_ORDER, {
    cid: context.cid,
    ...params,
  });
  return response.data;
};

const tool = (context: Context): Tool => ({
  method: 'get_payment',
  name: 'Get Payment',
  description: '이 도구는 카카오페이 주문 상태를 조회합니다.',
  parameters: getPaymentParameters(context),
  actions: {
    payment: {
      get: true,
    },
  },
  execute: getPayment,
});

이 Tool은 사용자에게 입력받은 tid(결제 고유번호)와 context로 설정한 cid(가맹점 코드)를 사용하여 해당 결제의 상세한 상태 정보를 반환합니다. 반환되는 정보에는 결제 상태, 결제 금액 등이 포함되어, 이를 통해 AI 에이전트가 사용자에게 정확한 결제 현황을 안내할 수 있습니다.

카카오페이 MCP Tool 종류

카카오페이 MCP Agent Toolkit은 다음과 같은 Tool들을 제공합니다:

결제 관련 Tool:

demo_payment: 데모 결제 링크 생성
ready_payment: 실제 결제 준비
approve_payment: 결제 승인
get_payment: 결제 상태 조회
cancel_payment: 결제 취소

정기결제 관련 Tool:

request_subscription: 정기결제 요청
get_subscription: 정기결제 상태 조회
inactive_subscription: 정기결제 비활성화

아키텍처 설계

전체 구조

┌─────────────────┐    ┌───────────────────┐    ┌─────────────────┐
│    AI Agent     │    │     MCP Server    │    │  KakaoPay API   │
│   (Claude/GPT)  │◄──►│  (Agent Toolkit)  │◄──►│   (Open API)    │
└─────────────────┘    └───────────────────┘    └─────────────────┘

동작 플로우

위에서 소개한 Tool들이 실제로 어떻게 동작하는지 “5000원짜리 커피 결제 링크 생성해 줘”라는 사용자 요청을 예시로 살펴보겠습니다.

1. 사용자 요청 분석 및 파라미터 추출

사용자가 자연어로 “커피 5000원짜리 결제 링크 만들어줘”라고 요청하면, LLM이 이를 분석하여 “결제 링크 생성”이라는 의도를 파악하고 demo_payment Tool 호출을 결정하고, 사용자 입력에서 필요한 정보를 추출합니다:

item_name: “커피”
total_amount: 5000

2. MCP 프로토콜 통신

Tool 호출 요청이 MCP 프로토콜을 통해 카카오페이 MCP Server에 전달됩니다.

3. 카카오페이 API 호출

MCP Server는 받은 파라미터를 카카오페이 Open API 형식에 맞춰 변환한 후, 실제 카카오페이 결제 시스템에 데모 결제 링크 생성을 요청합니다.

4. 결과 반환

카카오페이 API에서 반환된 결제 링크와 TID 정보를 MCP Server가 받아 LLM에게 전달하고, LLM은 이를 바탕으로 사용자에게 결제 링크와 함께 안내 메시지로 응답합니다.

이러한 플로우를 통해 복잡한 결제 API 연동 과정이 사용자에게는 단순한 자연어 대화로 추상화됩니다.

핵심 컴포넌트

카카오페이 MCP Agent Toolkit을 구성하는 핵심 컴포넌트는 다음과 같습니다:

MCP Server (modelcontextprotocol/): 카카오페이 API와 AI 에이전트 간의 중계 역할
Shared Core (shared/): 모든 프레임워크에서 공통으로 사용하는 핵심 모듈

API Client (client.ts): 카카오페이 Open API와의 HTTP 통신을 담당
API Handler (api.ts): MCP 메서드 호출을 카카오페이 API 요청으로 변환
Configuration (configuration.ts): 화이트리스트 기반 도구 필터링 및 권한 관리
Tools Registry (tools.ts): 모든 결제 도구들을 등록하고 관리

Payment Tools (shared/payment/): 결제 관련 도구들 (데모결제, 결제준비, 승인, 취소, 조회)
Subscription Tools (shared/subscription/): 정기결제 관련 도구들 (요청, 비활성화, 조회)
Framework Integrations: LangChain, OpenAI, AI SDK 등 각 프레임워크별 최적화된 모듈

멀티 프레임워크 지원

MCP 외에도 여러 AI 프레임워크와 연동할 수 있는 다양한 모듈을 지원합니다:

LangChain Integration: LangChain의 tool 시스템과 연동
Vercel AI SDK Integration: Vercel AI SDK의 tool 기능 지원
OpenAI Function Calling: OpenAI의 function calling 직접 지원

각 프레임워크별 사용 예시:

LangChain:

const kakaopayAgentToolkit = new KakaoPayAgentToolkit({
  secretKey: process.env.KAKAOPAY_SECRET_KEY!,
  configuration: {
    context: { cid: 'TC0ONETIME' },
    actions: { payment: { demo: true } },
  },
});

const agent = createReactAgent({
  llm: new ChatOpenAI({ model: 'gpt-4o' }),
  tools: kakaopayAgentToolkit.getTools(),
});

const result = await agent.invoke({
  messages: [{ role: 'user', content: '5000원짜리 커피 결제 링크 생성해 줘' }],
});

Vercel AI SDK:

const kakaopayToolkit = new KakaoPayAgentToolkit({
  secretKey: process.env.KAKAOPAY_SECRET_KEY!,
  configuration: {
    context: { cid: 'TC0ONETIME' },
    actions: { payment: { demo: true } },
  },
});

const { text: result } = await generateText({
  model: openai('gpt-4o'),
  tools: kakaopayToolkit.getTools(),
  maxSteps: 10,
  prompt: '5000원짜리 커피 결제 링크 생성해 줘',
});

OpenAI Function Calling:

const kakaopayAgentToolkit = new KakaoPayAgentToolkit({
  secretKey: process.env.KAKAOPAY_SECRET_KEY!,
  configuration: {
    context: { cid: 'TC0ONETIME' },
    actions: { payment: { demo: true } },
  },
});

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: '5000원짜리 커피 결제 링크 생성해 줘' }],
  tools: kakaopayAgentToolkit.getTools(),
});

실제 사용 사례

MCP & Agent Toolkit을 활용하면 다양한 결제 시나리오를 AI와 연동할 수 있습니다. 아래는 실제 사용 예시입니다.

1. MCP 호스트와 연동하기

Claude, GPT 등 LLM을 지원하는 AI 도구(예: Claude Desktop, Cursor, Windsurf 등)에서 카카오페이 MCP 서버를 연동하는 방법과 실제 대화 예시는 다음과 같습니다.

호스트 연동

호스트 mcp 설정 파일에 추가:

{
  "mcpServers": {
    "kakaopay": {
      "command": "npx",
      "args": [
        "-y",
        "@kakaopay-develop/mcp",
        "--tools=all",
        "--cid=TC0ONETIME"
      ],
      "env": {
        "KAKAOPAY_SECRET_KEY": "YOUR_KAKAOPAY_SECRET_KEY"
      }
    }
  }
}

실제 대화 예시

사용자: “5000원짜리 커피 PC 결제 링크 생성해 줘”

AI: “5000원짜리 커피 PC 결제 링크를 생성해 드리겠습니다.”

결과:

5000원짜리 커피 PC 결제 링크를 생성했습니다!
결제 정보:
상품명: 커피
금액: 5,000원
결제 고유번호(TID): T88b5794757b75da9818
PC 결제 링크:
https://online-payment.kakaopay.com/mockup/bridge/pc/pg/one-time/payment/884a56694f91fc01dad8b45634ee3f73fa7776eebfb128349c1000af31a20758?kpayTid=T88b5794757b75da9818
위 링크를 클릭하시면 카카오페이 PC 결제 화면으로 이동합니다. 이 링크는 데모 결제 링크이므로 실제 결제가 이루어지지는 않습니다.

2. AI SDK를 이용한 카카오페이 챗봇 만들기

Agent Toolkit과 AI SDK를 결합하면 실제 챗봇 서비스도 손쉽게 구현할 수 있습니다. 이 섹션에서는 예제로 개발한 챗봇 프로젝트를 기반으로, 실전 챗봇 구현 과정을 소개합니다.

프로젝트 구조

예제 프로젝트는 Next.js 기반의 Vercel AI SDK와 카카오페이 Agent Toolkit을 결합하여, 실제 결제 시나리오를 대화형 챗봇으로 구현합니다.

주요 구성 요소

Next.js 기반 웹 애플리케이션
Vercel AI SDK를 활용한 AI 통신
카카오페이 Agent Toolkit 연동
카카오페이 페이봇 스타일의 UI 디자인

주요 구현 포인트

Agent Toolkit 연동

카카오페이 AI SDK를 이용해서 결제 관련 도구를 등록합니다.
위의 “멀티 프레임워크 지원” 섹션에서 Vercel AI SDK 예시를 참고하세요.

대화형 UI 구현 (AI SDK UI 활용)

Vercel AI SDK의 useChat 훅 등 UI 컴포넌트를 활용해, 사용자가 자연어로 결제 요청, 상태 조회, 취소 등을 입력할 수 있는 대화형 챗봇 UI를 구현합니다.
챗봇은 결제 링크, 상태, 취소 결과 등을 실시간으로 안내하며, 카카오페이 페이봇 스타일의 UI로 일관된 사용자 경험을 제공합니다.
예시:

import { useChat } from 'ai/react';

const { messages, input, handleInputChange, handleSubmit } = useChat({
  api: '/api/chat',
  initialMessages: [
    {
      id: '1',
      role: 'system',
      content:
        '카카오페이 결제 도우미입니다. 결제 링크 생성, 상태 조회, 취소 등을 도와드립니다.',
    },
  ],
});

실제 동작 예시

“5000원짜리 커피 결제 링크 생성해 줘” → 결제 링크 생성 및 안내
“방금 링크 결제 상태 조회해 줘” → 결제 상태(대기/완료 등) 안내
“PC 결제 취소해 줘” → 결제 취소 및 결과 안내

아래는 실제 챗봇 UI 시연입니다.

카카오페이 MCP 챗봇 대화 시연 영상

카카오페이 MCP 챗봇 대화 시연

이러한 챗봇 구현을 통해 개발자들은 Agent Toolkit의 실제 활용 사례를 확인하고, 자신만의 결제 연동 서비스를 구축할 수 있습니다.

무엇을 배웠나?

이번 프로젝트를 통해 얻은 주요 인사이트는 다음과 같습니다.

1. 사람 중심의 AI 활용

가장 큰 깨달음은 “사람이 AI를 도구로 활용한다”는 점이었습니다. AI가 결제 API를 호출할 수 있게 되었다고 해서, 결제 시스템의 핵심 로직이나 비즈니스 규칙이 바뀌는 것은 아닙니다.

중요한 것은 여전히 사람이 설계하고 구현해야 한다는 점입니다:

어떤 API를 AI가 호출할 수 있는지
어떤 제한사항을 둘 것인지
어떻게 안정적으로 운영할 것인지

2. 표준화의 중요성

MCP 같은 표준 프로토콜을 사용함으로써 얻은 이점들이 많았습니다:

프레임워크 독립성 확보
개발 생산성 향상
유지보수성 개선
커뮤니티 생태계 활용

3. 체계적인 개발 접근

결제 API와 AI 연동 범위를 결정할 때 신중한 검토가 필요했습니다. 카카오페이 Open API가 이미 다양한 환경에서 검증된 API들이므로, 체계적인 검토를 통해 모든 결제 API를 제공하기로 결정했습니다:

1단계: API 전체 검토 및 활용성 평가
2단계: MCP Tool 구조 설계 및 구현
3단계: 프레임워크별 연동 모듈 개발
4단계: 실제 챗봇 예제 구현

향후 계획

1. AI 에이전트 특화 결제 플로우 개발

현재의 카카오페이 MCP는 기존 결제 플로우를 기반으로 하고 있어, AI 에이전트 환경에서는 일부 한계가 있습니다. 앞으로는 AI 에이전트가 더 자연스럽고 효율적으로 결제를 처리할 수 있도록 전용 결제 플로우를 개발할 예정입니다.

2. 기능 확장

Python SDK 제공: 다양한 언어 환경에서 MCP Toolkit을 활용할 수 있도록 Python SDK를 추가로 제공합니다.
TypeScript SDK 프레임워크 확장: AWS Bedrock 등 추가 AI 프레임워크 지원을 제공합니다.

3. 개발자 경험 개선

Tool 설계 개선: 더 직관적인 Tool 인터페이스 설계
문서화: 상세한 사용 가이드와 예제 제공

마치며

AI 에이전트와 결제 API 연동은 처음에는 새로운 가능성의 문을 여는 흥미로운 도전이었습니다. 체계적인 접근과 표준화된 프로토콜을 통해 개발자들이 쉽게 활용할 수 있는 유용한 시스템을 구축할 수 있었습니다.

이 프로젝트를 통해 깨달은 것은 AI 기술이 개발자의 생산성을 획기적으로 높여주면서도, 동시에 개발자의 창의성이 더욱 중요해졌다는 점입니다. AI는 우리가 더 본질적인 문제 해결에 집중할 수 있도록 도와주는 강력한 도구가 되고 있습니다.

앞으로도 AI 기술의 발전 속도는 더욱 가속화될 것입니다. 이러한 변화를 적극적으로 수용하고, 더 많은 개발자들이 AI의 혜택을 누릴 수 있도록 지속적으로 개선해 나가겠습니다. 카카오페이 MCP Agent Toolkit이 여러분의 AI 개발 여정에 작은 도움이 되기를 바랍니다.