mcpField
T
Toss Payments

Toss Payments

Local
appmonster.co.krFinance0Updated 6d ago
RepositoryVisit website

About Toss Payments

Toss Payments is an MCP server for accessing core Toss Payments operations, including payment lookups, transaction lists, and settlements. It also supports cancellations and refunds, with human approval options for its write operation.

Key features

  1. 01Look up payment details
  2. 02List approved and canceled transactions
  3. 03Read settlement amounts and fees
  4. 04Cancel or partially refund payments

Use cases

  1. 01Check a payment by paymentKey or orderId
  2. 02Reconcile transactions over a date range
  3. 03Review settlement fees and payouts
  4. 04Request approval before canceling a payment

MCP support

Exposes Toss Payments lookup, transaction, settlement, and cancellation tools to MCP clients. Cancellation can use a confirmation token or route approval through OK Agent.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "groove79-mcp-toss-payments": {
      "command": "npx",
      "args": [
        "-y",
        "@appmonster/mcp-toss-payments"
      ],
      "env": {
        "TOSS_SECRET_KEY": "<TOSS_SECRET_KEY>",
        "OKAGENT_API_KEY": "<OKAGENT_API_KEY>",
        "KMCP_WRITE_MODE": "<KMCP_WRITE_MODE>"
      }
    }
  }
}
Run commandnpx -y @appmonster/mcp-toss-payments
Environment variables to set
TOSS_SECRET_KEYSecretSecret key (test_sk_… or live_sk_…) from the Toss Payments developer center
OKAGENT_API_KEYSecretOK Agent key (free at okagent.kr) — writes then wait for your OK on KakaoTalk. Unset: writes ask for confirmation in the chat first.
KMCP_WRITE_MODEapproval | confirm | direct (default: approval if OKAGENT_API_KEY is set, else confirm)

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@appmonster/mcp-toss-payments0.2.0

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

@appmonster/mcp-toss-payments

MCP server for Toss Payments (토스페이먼츠) core API. An agent can look up a payment, reconcile transactions, read settlements — and cancel/refund, which is the one tool that moves real money and is built to run behind a human approval (OK Agent).

토스페이먼츠 MCP 서버 — 결제 조회, 거래 내역, 정산, 취소/환불(승인 게이트).

Tools

ToolAccessWhat it does
toss_get_paymentreadpaymentKey 또는 orderId로 결제 1건: 상태, 금액, 잔액, 수단, 취소 이력, 영수증 URL
toss_cancel_paymentwrite전체/부분 취소. 가상계좌는 환불계좌 필수. Idempotency-Key 자동 부여
toss_list_transactionsread기간별 거래(승인·취소) 목록, 최대 5000건, startingAfter 커서
toss_list_settlementsread정산 내역(수수료·부가세·지급액), 매출일/지급일 기준, 합계 포함

Setup

  1. https://developers.tosspayments.com → 내 개발정보 → API 키. 먼저 test_sk_…로 시작하세요 (테스트 결제 데이터로 동작).
  2. MCP client config:
{
  "mcpServers": {
    "toss-payments": {
      "command": "npx",
      "args": ["-y", "@appmonster/mcp-toss-payments"],
      "env": { "TOSS_SECRET_KEY": "test_sk_…" }
    }
  }
}
Human approval for cancels (strongly recommended with a live key)
"OKAGENT_API_KEY": "ok_…"

Without it, write tools still never run blind: the first call returns a preview and a confirm_token, and the agent re-calls only after you agree in the chat. With an OK Agent key (free, 200/month) the request goes to your phone instead — approve on KakaoTalk, with a log. KMCP_WRITE_MODE=direct turns the check off for scripts you fully trust.

With a live_sk_ key the server prints a warning at start if no approval hook is configured.

Safety notes

  • toss_cancel_payment is irreversible. The tool description tells the agent to call toss_get_payment first and check balanceAmount.
  • Every cancel carries an Idempotency-Key (UUID, or the caller's own key) so a retried call cannot refund twice. Keys are valid 15 days on Toss's side.
  • Test-key servers tag every tool description with [TEST KEY — sandbox data] so the agent never mistakes sandbox numbers for real revenue.

Development

pnpm --filter @appmonster/mcp-toss-payments test

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.