MCP for AI agents — Giftronaut API

Do I need a separate credential for MCP?

No. MCP reuses your existing OAuth2 client credentials — the same client_id you use for /api/v1/orders also authenticates /api/v1/mcp sessions. One credential per app, one rate-limit bucket, one audit trail.

Why does the MCP endpoint reject my `client_credentials` token?

MCP requires user identity (the acting_as_app_client_id claim) which the client_credentials grant cannot produce. Use the browser sign-in flow (MCP Client Setup) — your existing client_credentials tokens still work for the REST surface.

What do the common error codes mean?

Error	Meaning	What to do
`401 invalid_token`	Token rejected (see above)	Reconnect via browser sign-in
`403 DRAFT_ACCESS_DENIED`	Draft belongs to another organization or environment, or does not exist	Check the `draftId`; create a new draft if needed
`409 DRAFT_ALREADY_EXECUTED`	The same draft cannot be executed twice	Create a new draft for a new order
`409 ORDER_NOT_CANCELABLE`	Only SCHEDULED orders more than 10 minutes before send time can be canceled	Contact support for manual handling
`410 DRAFT_EXPIRED`	Drafts expire ~1 hour after creation	Create a new draft
`429 RATE_LIMITED`	Too many requests	Wait for the `Retry-After` interval
`429 DAILY_SPEND_CAP_EXCEEDED`	The org's daily USD spend cap was reached	Ask your account manager to raise the limit
`500 INTERNAL_ERROR` (retryable)	Unexpected server error	Retry with the same `idempotencyKey`; contact support if it persists

Where do I see what tools my agent invoked?

Open the portal Logs page and click the MCP tab. Each row shows the tool name, request id, env, status, and duration. Click any row for the full invocation detail. See Monitoring & logs for the column schema.

Can I use a Sandbox credential with MCP?

No — MCP is production-only. Sandbox credentials are hidden from the MCP sign-in screen, and existing sandbox tokens are rejected on /api/v1/mcp with 401 invalid_token telling you to reconnect with a production credential. Production apps are created in the portal (Apps → Create new app → Production) and are active immediately for MCP delegation. Sandbox credentials continue to work for the REST API. For safe experimentation over MCP, use giftronaut_send_test_email (email preview), dryRun=true on cancel/resend, and the draft → execute confirmation flow.

How are destructive operations protected from LLM mistakes?

Every destructive tool (cancel_order, delete_recipient, delete_recipient_group, remove_recipient_from_group) requires confirm="YES" exactly — case-sensitive. Several support dryRun=true for a preview. Value-moving order tools additionally enforce a daily USD spend cap server-side.

How do I disable a tool I don't want my agents to use?

Operators can flip individual tools off per environment via the portal kill-switch admin page. Disabled tools disappear from tools/list for new sessions and return TOOL_DISABLED (503) if forced.

What's the deprecation policy?

Tools follow the same deprecation cadence as the REST API: minimum 90-day notice posted to the changelog, deprecated tools tagged in tools/list for the entire window, and removed only after the notice expires. Parameter additions are always backward compatible.

I'm reading older docs that mention 24 or 31 tools. Is that still accurate?

The current surface is 47 tools across 11 domains. The growth path since the original Phase 1 launch:

24 → 30 — added find_recipient_by_email, get_recipient_group_with_members, delete_recipient_group, remove_recipient_from_group, parse_recipients_csv, batch_create_recipients
30 → 31 — added request_ach_top_up (production-only ACH funding requests)
31 → 43 — added Campaigns (6 tools) + Templates (5 tools) + update_recipient_group — closing the last gap between REST API and MCP so any business operation available over HTTP is now invokable via natural language
43 → 46 — added request_order_limit_increase (queued daily/monthly spend limit increase requests)
46 → 47 — added reveal_reward_links (unmasks reward-link redeem URLs, gated behind an explicit confirm="YES")

How can the agent top up my account?

Two paths:

ACH transfer — call giftronaut_request_ach_top_up with the amount (≥ $100), company name, EIN, and billing details. Production-only — sandbox credentials return SANDBOX_NOT_SUPPORTED. Approval takes 1-3 business days; you'll receive a webhook notification — BALANCE_ACH_APPROVED if approved, or BALANCE_ACH_REJECTED if declined.
Credit card — requires interactive 3DS / fraud-check, so the user must sign in to the portal at portal.giftronaut.com/marketing/sign-in, open Account Balance in the left navigation, click ADD FUNDS +, and choose Credit Card. MCP cannot complete this flow on the user's behalf.

Balance, order, draft, and execute tools all attach an advisory hints field to the success envelope when the available balance falls below the configured threshold (default $50) — see the Balance tools section for the exact shape.