Official Porkbun MCP Server

Renew Mailbox

renew_mailbox

Idempotent

Instructions

Spends account credit, or pays directly by card (pay_with_card) or in USDC (pay_with_usdc). Add a year to an email hosting mailbox now, at its renewalPrice from list_mailboxes ($36.00, or a legacy price for mailboxes that still qualify). Set-up mailboxes already renew on their own when due (autoRenews: true), so use this when the user wants to pay early or keep a trial mailbox. Name the mailbox with mailbox_id or address. Tell the user the price first; cost_cents must match, and dry_run: true with cost_cents: 0 quotes it and shows the new expiry (expiresAfter).

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
`domain`	Yes	Domain the mailbox is on.
`address`	No	Or the mailbox address (`me` or `me@example.com`).
`dry_run`	No	If true, quote and validate without renewing.
`cost_cents`	Yes	The mailbox's `renewalPrice`, e.g. 3600. Integer US cents: 803 means $8.03, not $803.
`mailbox_id`	No	The mailbox `id` from `list_mailboxes`.
`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.

Addedv0.51.1Oct 14, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description goes well beyond them: it discloses that credit is spent by default, that a saved card is never charged by a purchase itself, that card holds are released on failure, that a failed post-payment purchase stays as account credit (keptAsCredit), and it names error codes (INSUFFICIENT_FUNDS, VERIFICATION_REQUIRED, PAYMENT_REQUIRED) with their payloads. It does not describe pagination or return shape, but no output schema exists and the errors are the material behavior here.

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?

Front-loaded with the bolded spend/price rule, but the body is three very dense paragraphs where payment-path detail, retry choreography and CLI commands are interleaved. Load-bearing content is present, yet the buying-a-domain guide link is tangential to a mailbox renewal and several ideas (tell the user the amount, retry with the same arguments) repeat across paragraphs, so it is longer than the minimum an agent needs.

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?

For a 9-parameter, money-moving tool with no output schema, the description supplies the missing contract: default funding source, all three payment modes, the two-step async payment handshake, error recovery, and the human-verification escape hatch. Nothing needed to call it correctly is absent.

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

Parameters5/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds non-obvious semantics the schema lacks: cost_cents must match renewalPrice from list_mailboxes, dry_run with cost_cents: 0 acts as a quote returning expiresAfter, money is integer cents to be stated to the user in dollars, and card_payment_id/usdc_checkout_id must be sent with the same arguments as the originating call.

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?

Opens with a specific verb+resource+scope: 'Add a year to an email hosting mailbox now', and immediately differentiates from setup_mailbox/create_mailbox by noting set-up mailboxes already auto-renew so this is for early payment or trial mailboxes. An agent can place it against siblings like renew_domain and list_mailboxes without opening another schema.

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?

Explicitly states when to use it versus the auto-renew default, and lays out five ordered fallback paths for insufficient funds, each with the specific alternative tool (top_up_account_credit, top_up_with_card_mpp, top_up_with_usdc, configure_auto_topup) and the condition that selects it. The 'if you do not move money on a user's behalf, hand it back' clause is a genuine when-not rule.

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

Deploy Server

Renew Mailbox

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools