Official Porkbun MCP Server

Renew Domain

renew_domain

Idempotent

Spends account credit, or pays directly by card (pay_with_card) or in USDC (pay_with_usdc). Renews an existing domain in the authenticated account.

Instructions

Spends account credit, or pays directly by card (pay_with_card) or in USDC (pay_with_usdc). Renews an existing domain in the authenticated account. The cost_cents parameter must exactly match the current renewal price returned by check_domain (in cents). The domain must be opted in to API access (per-domain or global toggle in account settings), and only the user can turn that on: check apiAccess in get_domain or list_domains before starting, and if it is off, tell the user rather than finding out from API_ACCESS_DISABLED. Domains registered within the last 30 days, or already renewed within the last 30 days, cannot be renewed yet — the API returns RENEWAL_TOO_SOON with renewableAt, the date it becomes renewable; nothing is charged, so tell the user that date rather than retrying. Premium domain renewals are not supported via API. Idempotency-safe: retries within 24 hours don't double-charge.

How a purchase is paid. From prepaid account credit by default; a card saved at Porkbun is never charged by a purchase itself. Or directly, for this one purchase: pay_with_card: true (the user's card from their Stripe Link agent wallet, held and charged only if the purchase succeeds) or pay_with_usdc: true (USDC on Base over x402). If the credit is short, the call fails with INSUFFICIENT_FUNDS carrying cost, balance, shortfall, topUpAvailable and usdcAmountToCover (dry_run: true reports the same without charging). Ways forward, simplest first, always telling the user the dollar amount and getting their OK: (1) if they use Stripe Link, retry this exact call with pay_with_card: true; (2) if you can pay x402 (a wallet tool, or this server has PORKBUN_X402_PRIVATE_KEY), retry with pay_with_usdc: true; (3) when topUpAvailable is true a card is saved: top_up_account_credit (amount_cents at least topUpAmountToCover, or omit it for their configured amount), then retry; (4) add credit with top_up_with_card_mpp (Link) or top_up_with_usdc (for usdcAmountToCover, which allows for Coinbase's ~1% fee), then retry; (5) the user adds credit at https://porkbun.com/account/credit. If a purchase fails with VERIFICATION_REQUIRED, the phone (send_phone_verification_code then confirm_phone_verification) and the email (send_email_verification_code then confirm_email_verification) can both be verified without leaving the conversation, the user reading out each code. Suggest configure_auto_topup if they want credit refilled automatically. Money parameters are integer cents: state amounts to the user in dollars (cost_cents: 1108 is $11.08). If you do not move money on a user's behalf, hand it back instead: tell them the shortfall and that they can add it with buy account credit at https://porkbun.com/account/credit, then retry once they have.

Buying for a new or unfunded account: the whole path, including what only the human can do, is at https://porkbun.com/llms/guides/buy-a-domain-from-an-agent. Paying directly in USDC (no account credit needed): set pay_with_usdc: true. If this server has a wallet configured (PORKBUN_X402_PRIVATE_KEY, local installs only), the payment is signed and the purchase completes in this one call. Otherwise the result is status: PAYMENT_REQUIRED with a checkoutId, an x402Url and a payUrl, and nothing is charged: pay the x402Url with a wallet tool that pays x402 URLs (for example Coinbase's awal x402 pay <x402Url> --scheme auth-capture), or have the user pay the payUrl page, then call this tool again with the same arguments plus usdc_checkout_id. Tell the user the dollar amount first. If the purchase fails after payment, the payment is NOT returned to the wallet: it stays on the Porkbun account as credit (the error says keptAsCredit: true with the new balance), so retry without pay_with_usdc to buy from that credit.

Paying directly by card, with a hold (no account credit needed): set pay_with_card: true when the user pays with Stripe Link. The result is status: PAYMENT_REQUIRED with a payUrl and a cardPaymentId; nothing is charged. Pay the payUrl with an MPP wallet tool. With Link's CLI that is two commands: link-cli mpp pay <payUrl> -X POST --context "..." (context at least 100 characters) creates a spend request the user approves in Link; once approved, complete it with link-cli mpp pay <payUrl> --spend-request-id <lsrq_id> -X POST. That only authorizes the card. If link-cli answers NOT_AUTHENTICATED, run link-cli auth login first (a one-time device login the user approves). Then call this tool again with the same arguments plus card_payment_id: if the purchase succeeds the card is charged, and if it fails the hold is released and nothing is charged. The link works until expiresAt; if that passes before it is paid, call this tool again without card_payment_id for a fresh link instead of paying the old one.

Input Schema

TableJSON Schema

Name	Required	Description
`cost`	No	Deprecated alias of `cost_cents`, same unit (integer US cents). Send `cost_cents` instead.
`domain`	Yes	Domain name to renew, e.g. `example.com`. Must already be in your account.
`dry_run`	No	If true, validate and preview (`dryRun: true`, `wouldSucceed`) WITHOUT renewing or charging.
`cost_cents`	No	Renewal price. Must match the value returned by `check_domain`. Required. Integer US cents: 803 means $8.03, not $803.
`pay_with_card`	No	Pay for this purchase by card from the user's Stripe Link agent wallet (MPP), with a hold: charged only if the purchase succeeds. Tell the user the amount first.
`pay_with_usdc`	No	Pay for this purchase directly in USDC on Base (x402) instead of from account credit. Tell the user the amount first.
`card_payment_id`	No	The cardPaymentId from an earlier PAYMENT_REQUIRED (pay_with_card), once its payUrl has been paid. Send it with the same arguments as that call.
`usdc_checkout_id`	No	The checkoutId from an earlier PAYMENT_REQUIRED result, once its x402Url or payUrl has been paid. Send it with the same arguments as that call.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.51.1Oct 14, 2026

addedInput schema / properties / card_payment_id

Added value: +{
+  "description": "The cardPaymentId from an earlier PAYMENT_REQUIRED (pay_with_card), once its payUrl has been paid. Send it with the same arguments as that call.",
+  "type": "string"
+}

addedInput schema / properties / pay_with_card

Added value: +{
+  "description": "Pay for this purchase by card from the user's Stripe Link agent wallet (MPP), with a hold: charged only if the purchase succeeds. Tell the user the amount first.",
+  "type": "boolean"
+}

addedInput schema / properties / pay_with_usdc

Added value: +{
+  "description": "Pay for this purchase directly in USDC on Base (x402) instead of from account credit. Tell the user the amount first.",
+  "type": "boolean"
+}

addedInput schema / properties / usdc_checkout_id

Added value: +{
+  "description": "The checkoutId from an earlier PAYMENT_REQUIRED result, once its x402Url or payUrl has been paid. Send it with the same arguments as that call.",
+  "type": "string"
+}

Changed6 schema fields changedv0.39.4Oct 1, 2026

changedInput schema / properties / cost / description

Previous value: -"Renewal price in cents. Must match the value returned by `check_domain`."New value: +"Deprecated alias of `cost_cents`, same unit (integer US cents). Send `cost_cents` instead."

removedInput schema / properties / cost / exclusiveMinimum
```
Removed value: -0
```
addedInput schema / properties / cost / minimum
```
Added value: +-9007199254740991
```

addedInput schema / properties / cost_cents

Added value: +{
+  "description": "Renewal price. Must match the value returned by `check_domain`. Required. Integer US cents: 803 means $8.03, not $803.",
+  "exclusiveMinimum": 0,
+  "maximum": 9007199254740991,
+  "type": "integer"
+}

addedInput schema / properties / dry_run

Added value: +{
+  "description": "If true, validate and preview (`dryRun: true`, `wouldSucceed`) WITHOUT renewing or charging.",
+  "type": "boolean"
+}

changedInput schema / required

Previous value: -[
-  "domain",
-  "cost"
-]New value: +[
+  "domain"
+]

First observedv0.4.1Jun 12, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only say readOnlyHint=false and idempotentHint=true; the description goes far beyond by disclosing exactly what gets charged, that retries within 24 hours do not double-charge, that nothing is charged on RENEWAL_TOO_SOON or INSUFFICIENT_FUNDS, that a failed card purchase releases the hold, and that a failed USDC purchase keeps funds as account credit (keptAsCredit). It also enumerates error codes and the PAYMENT_REQUIRED / cardPaymentId / checkoutId retry protocol.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded and uses bold headers, but at roughly 900 words it is heavily oversized, and the USDC/card PAYMENT_REQUIRED mechanics are explained once in "How a purchase is paid" and then re-explained in two later paragraphs. A money-moving tool warrants depth, but the redundancy costs it here.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and 8 parameters including two payment channels, the description carries the return-shape burden itself and does so: it documents status: PAYMENT_REQUIRED, dryRun/wouldSucceed, x402Url/payUrl/expiresAt, INSUFFICIENT_FUNDS fields, VERIFICATION_REQUIRED resolution path, and the retry protocol. An agent has everything needed to complete or safely abandon a renewal.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all 8 parameters and baseline is 3. The description adds real operational meaning: cost_cents must exactly match the check_domain price, money values are integer cents that must be stated to the user in dollars, and card_payment_id / usdc_checkout_id must be re-sent with the identical arguments from the original call. That is substantive beyond the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb and resource ("Renews an existing domain in the authenticated account") and is immediately distinguishable from siblings like register_domain, transfer_domain, and renew_mailbox. The scope is unambiguous: an already-owned domain, not a new registration.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lays out explicit preconditions (API access opt-in, verified via apiAccess in get_domain/list_domains), exclusions (domains registered or renewed in the last 30 days, premium domains not supported), and error-driven routing to named alternatives (top_up_account_credit, top_up_with_card_mpp, top_up_with_usdc, top_up_account_credit). It even specifies the order of fallbacks and when to check_domain for cost_cents.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Renew Domain

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools