MCP for AI agents — Giftronaut API

Authentication & authorization

OAuth 2.1 with PKCE S256 for browser clients; client_credentials for server agents (REST surface only — MCP requires user identity).
RFC 7591 Dynamic Client Registration — agents self-register at POST /oauth2/register on the first call.
RFC 8707 audience binding — MCP tokens must carry aud=["https://api.giftronaut.com/api/v1/mcp"] via the resource=https://api.giftronaut.com/api/v1/mcp token-exchange parameter (matches PRM resource field). REST tokens are rejected by the MCP endpoint by design.
RFC 9728 Protected Resource Metadata — discoverable at /.well-known/oauth-protected-resource (public, unauthenticated).
Scopes — identical to the REST API. A missing scope returns 403 insufficient_scope; the response includes WWW-Authenticate for clients that auto-elevate.

Server-side guards

Guard	Effect
Daily USD spend cap	Pre-validates any tools that can move funds. Exceeding it returns `DAILY_SPEND_CAP_EXCEEDED`. Configured per organization.
Idempotency cache	24-hour `(org_id, env, tool_name, key)` cache. Replays the original response on retry — safe under network failure.
Confirmation guard	Destructive tools (`cancel_order`, `delete_recipient`, `delete_recipient_group`, `remove_recipient_from_group`) require `confirm="YES"` exactly — case-sensitive, no truthy aliases.
Tool kill switch	Operators can disable individual tools per environment. Disabled tools are hidden from `tools/list` and return `TOOL_DISABLED` (503) if forced.
Tool PIN	Optional per-tool personal-identification gate for high-risk operations.
Input / output sanitization	Tool poisoning and indirect prompt injection patterns are stripped from inputs and outgoing JSON payloads.

Rate limits

MCP is production-only, so production limits apply:

Bucket	Limit
Per credential	60/min
Per tool (sub-bucket)	10/min
DCR registration	5/min/IP

Exceeding any bucket returns 429 with Retry-After.

Audit & logs

Every tool invocation writes to audit_events with masked inputs and hashed outputs. See Monitoring & logs for the dashboard view and column schema.

IP allowlist

Production AppClients can require an IP allowlist. The same IP allowlist rules used for REST API calls also apply to MCP tool calls. Browser flow is exempt during sign-in, but the resulting MCP session inherits the same restriction on tool calls.