카카오페이 MCP Agent Toolkit — AI 에이전트로 결제 API 연동하기

"5000원짜리 커피 결제 링크 생성해 줘."

이 한 마디를 받은 AI가 스스로 카카오페이 API를 호출해서 결제 링크와 TID까지 돌려준다면? 카카오페이가 MCP Agent Toolkit을 오픈소스로 공개하면서 이게 실제로 가능해졌다.

왜 MCP를 선택했나

기존에도 AI와 결제 API를 연동하는 방법은 있었다. OpenAI function calling이나 LangChain 도구를 쓰면 됐다. 문제는 프레임워크 종속성이었다. 어느 날 새로운 LLM이 등장하면 그때마다 구현을 다시 해야 한다.

PayPal, Stripe 같은 글로벌 핀테크 기업들은 이미 AI 연동 솔루션을 제공하고 있다. 카카오페이가 선택한 답은 표준화였다. MCP(Model Context Protocol)는 특정 프레임워크에 묶이지 않는 공개 표준이다.

[💡 잠깐! 이 용어는?] MCP(Model Context Protocol): AI 어시스턴트가 외부 도구나 데이터에 접근할 수 있게 해주는 공개 표준 프로토콜. Anthropic이 처음 제안했고 Claude Desktop, Cursor, VS Code 등 주요 AI 도구가 지원한다.

툴킷 구성: 8개의 Tool

카카오페이 MCP Agent Toolkit은 결제 흐름 전체를 8개의 Tool로 감싸고 있다.

AI가 자연어를 받으면 이 Tool 중 하나를 선택하고, 필요한 파라미터를 추출해서 MCP 서버에 요청한다. 서버는 카카오페이 Open API를 호출하고 결과를 돌려준다.

동작 흐름

비유하면 MCP 서버는 통역사다. AI는 "커피 결제 링크 줘"라는 말을 하고, 통역사가 카카오페이 API 언어로 바꿔서 전달한다. API의 응답도 AI가 이해할 수 있는 형태로 다시 번역해준다.

AI Agent (Claude/GPT)
    ↓ "5000원짜리 커피 결제 링크 생성해 줘"
MCP Server (Agent Toolkit)
    ↓ demo_payment 호출 + 파라미터 추출
KakaoPay Open API
    ↓ 결제 링크 + TID 반환
AI Agent → 사용자에게 안내

실제 코드: Tool 정의부터 연동까지

Tool 구현 구조 — 결제 상태 조회 예시다.

import { z } from "zod"
 
export const getPaymentParameters = () =>
  z.object({
    tid: z.string().describe("결제 고유 번호 (TID)"),
  })
 
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
}

파라미터를 Zod 스키마로 정의하면 AI가 어떤 값을 넣어야 하는지 자동으로 파악한다. LLM이 함수 설명과 파라미터 설명을 읽고 적절한 값을 채워 넣는 구조다.

LangChain 연동 — 기존 LangChain 워크플로우에 붙이는 방법이다.

import { KakaoPayAgentToolkit } from "@kakaopay/agent-toolkit-langchain"
import { createReactAgent } from "@langchain/langgraph/prebuilt"
import { ChatOpenAI } from "@langchain/openai"
 
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 연동 — Next.js 앱에서 바로 쓸 수 있다.

import { KakaoPayAgentToolkit } from "@kakaopay/agent-toolkit-ai-sdk"
import { openai } from "@ai-sdk/openai"
import { generateText } from "ai"
 
const kakaopayToolkit = new KakaoPayAgentToolkit({
  secretKey: process.env.KAKAOPAY_SECRET_KEY!,
  configuration: {
    context: { cid: "TC0ONETIME" },
    actions: {
      payment: { demo: true, approve: true, cancel: true, getPayment: true },
    },
  },
})
 
const { text: result } = await generateText({
  model: openai("gpt-4o"),
  tools: kakaopayToolkit.getTools(),
  maxSteps: 10,
  prompt: "5000원짜리 커피 PC 결제 링크 생성해 줘",
})

maxSteps: 10이 중요하다. AI가 여러 Tool을 순서대로 호출하는 멀티 스텝 워크플로우를 허용하는 설정이다. "결제 준비 → 승인 → 상태 조회" 같은 흐름을 한 번의 대화로 처리할 수 있다.

MCP 호스트 직접 연결

LangChain이나 Vercel AI SDK 없이 Claude Desktop, Cursor, Windsurf 같은 MCP 호스트에 직접 연결할 수도 있다.

{
  "mcpServers": {
    "kakaopay": {
      "command": "npx",
      "args": ["-y", "@kakaopay/agent-toolkit-mcp"],
      "env": {
        "KAKAOPAY_SECRET_KEY": "your-secret-key",
        "KAKAOPAY_CID": "TC0ONETIME"
      }
    }
  }
}

설정 파일 한 줄로 Claude Desktop에서 바로 카카오페이 결제를 제어할 수 있다.

프레임워크 지원 매트릭스

설계에서 얻은 인사이트

카카오페이 개발팀이 강조한 점이 있다. "AI는 도구일 뿐, 사람의 설계와 판단이 여전히 중요하다."

결제 흐름은 돈이 오가는 민감한 영역이다. 툴킷 설계에서 몇 가지 안전장치가 눈에 띈다. actions 설정으로 허용할 결제 작업을 명시적으로 지정해야 한다 — 아무 Tool이나 열어두는 게 아니라 demo: true, approve: true처럼 허가 목록 방식이다. 화이트리스트 기반 권한 관리다.

[💡 잠깐! 이 용어는?] CID(Client ID): 카카오페이 가맹점을 구분하는 식별자. 테스트 환경에서는 TC0ONETIME(단건결제), TCSUBSCRIP(정기결제) 같은 샌드박스 ID를 사용한다.

마무리

MCP는 "AI와 도구를 연결하는 공통 어댑터"다. 전력 콘센트처럼, 표준이 정해지면 각 기기가 별도 어댑터 없이 꽂아서 쓸 수 있다. 카카오페이의 MCP Agent Toolkit은 그 어댑터를 결제 API에 맞게 만든 것이다.

• 프레임워크 독립성이 필요하다 → MCP 표준이 답이다
• 다양한 LLM 프레임워크를 지원해야 한다 → 패키지별 SDK 구조로 해결
• 결제 같은 민감한 작업이다 → 화이트리스트 기반 권한 관리가 필수

Python SDK와 AWS Bedrock 지원도 향후 추가될 예정이라고 한다. 결제 외 다른 금융 API에도 같은 패턴을 적용할 수 있다.

참고:

• 카카오페이 기술 블로그: https://tech.kakaopay.com/post/kakaopay-mcp-agent-toolkit/
• MCP 공식 문서: https://modelcontextprotocol.io/