AI agent integration

Vauchflow exposes its API to AI agents through two integration surfaces: the MCP server for tool-calling agents like Claude Desktop and Cursor, and the Vauchflow Promotions Assistant Custom GPT in the OpenAI GPT Store. Both surfaces use scoped agent keys (vf_ak_*) that limit what the agent can do and expire automatically.

The MCP server ships with a full write-tool surface in v1: 7 read tools plus 9 write tools covering customers, vouchers, redemptions, campaigns, and webhooks. High-risk writes route through the operator approval queue before execution.

Which surface should I use?

Surface	Best for	Auth
MCP server	Claude Desktop, Cursor, Windsurf, custom MCP clients	vf_ak_* via X-API-Key
Custom GPT	Marketing and ops users in ChatGPT — no code required	vf_ak_* entered at runtime

Scoped agent keys

Agent keys (vf_ak_*) are short-lived API credentials designed specifically for AI callers. They limit the blast radius if a key is captured in a model’s context window or logs.

Available scopes

Scope	What it allows
VOUCHER_READ	Read voucher metadata and status
VOUCHER_VALIDATE	Validate voucher codes (no state change)
VOUCHER_REDEEM	Redeem voucher codes (consumes redemptions)
VOUCHER_WRITE	Create, update, delete vouchers
CAMPAIGN_READ	Read campaigns and rules
CAMPAIGN_WRITE	Create, update, end campaigns
CUSTOMER_READ	Read customer profiles and voucher assignments
CUSTOMER_WRITE	Create or update customer records
WEBHOOK_READ	List webhooks and delivery history
WEBHOOK_WRITE	Create, update, delete webhook endpoints
ANALYTICS_READ	Read aggregated analytics and reports

Billing endpoints are not grantable to agent keys in v1 — billing operations remain human-only.

TTL semantics

Agent keys expire between 1 and 90 days after creation (configurable at creation time; default 7 days). Expired keys return 401 Unauthorized. Agent keys are revocation-only. Calling POST /v1/api-keys/{id}/rotate against an agent key returns 422 Unprocessable Entity. To replace an agent key, revoke the old one and create a new key with the desired scopes.

Creating an agent key

Agent keys must be created with a secret key (vf_sk_*) — an agent key cannot create another agent key.

curl -X POST https://api.vauchflow.com/v1/api-keys/agent \
  -H "X-API-Key: vf_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude Desktop integration",
    "scopes": ["VOUCHER_READ", "VOUCHER_VALIDATE"],
    "ttlDays": 30
  }'

The response includes rawKey — the plaintext key shown once only. Store it securely.

See API reference — API keys for the full endpoint table.

Claude Desktop (MCP)

Paste the following into your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "vauchflow": {
      "url": "https://api.vauchflow.com/v1/mcp",
      "headers": {
        "X-API-Key": "vf_ak_your-agent-key-here"
      }
    }
  }
}

Restart Claude Desktop. You can now ask: “List my active campaigns” or “Is voucher SUMMER20 valid?”

For the full tool reference and protocol details, see MCP server.

Custom GPT in ChatGPT

The Vauchflow Promotions Assistant is a read-only Custom GPT that lets marketers and operations users query campaigns, validate voucher codes, and review redemption analytics in plain English — no code required.

The Vauchflow Promotions Assistant Custom GPT will be available in the OpenAI GPT Store. (Listing pending — search “Vauchflow Promotions Assistant” once published.)

Setup: when the GPT prompts for an API key, create a vf_ak_* agent key with scopes VOUCHER_READ, VOUCHER_VALIDATE, CAMPAIGN_READ, ANALYTICS_READ and paste it in. The key is stored in ChatGPT’s action authentication settings and is not shared with other users.

Caution

Write operations (“create a campaign”) return a friendly refusal from the GPT — they are not forwarded to the API. Use the dashboard or the REST API for write operations.

Operator approval queue

High-risk write operations submitted by agent keys (vf_ak_*) are held for operator review before execution. The MCP write tools create_campaign, update_campaign, create_voucher (count > 100), create_webhook, and delete_webhook route to this queue by default. Auto-executing tools (create_customer, update_customer, redeem_voucher, single create_voucher) run immediately without operator review.

When an operation routes to the queue, the agent receives a pending_approval JSON-RPC result (not an error) with an approval_id it can poll. See the MCP server tool table for per-tool dispositions.

See Approval queue for the default policy table, lifecycle states, and polling pattern.

Audit context

Add the Vauchflow-Agent-Context header to all agent requests to enable audit trail correlation. The header is optional but strongly recommended:

Vauchflow-Agent-Context: agent=claude-desktop;client=vauchflow-mcp@0.1.0;prompt_fp=8a3f1b2c;conv=conv_01H8XYZ

The prompt_fp value is an 8-character hex fingerprint computed client-side from the prompt text — the raw prompt is never stored or transmitted. See API reference — Request headers for the full field list and allowed agent values.