Skip to content
Vauchflow Docs

AI integration overview

Why this matters

Section titled “Why this matters”

Promotions infrastructure is one of the first things teams hand to AI agents. Campaign creation, voucher generation, and customer targeting are high-value but repetitive — exactly the tasks agents are best at. The problem is that a misconfigured campaign or a runaway bulk voucher generation can have real financial consequences, and most API surfaces were not designed with agent callers in mind. Other vendors now market AI features for promotions too (Voucherify’s Vincent AI, Talon.One’s AI capabilities) — Vauchflow’s distinctive choice is the governance surface: every agent write passes through a scoped key, high-risk operations land in an operator approval queue, and the full action lifecycle is surfaced via agent.action.* audit webhooks.

Vauchflow’s AI integration is designed around a single flow: an agent submits an action, the action passes through a scoped key that limits its blast radius, high-risk writes land in an operator approval queue, and the action executes only after a human reviews it. When a marketing agent in Claude Desktop says “launch a 20% Black Friday campaign capped at 1,000 redemptions”, the call goes through your scoped vf_ak_* agent key, hits the approval queue, your operator reviews the request on the dashboard, and only then the campaign is created. The alternative — giving an agent a full vf_sk_* secret key with no approval gate — is the failure mode this architecture is designed away from.

The two integration layers

Section titled “The two integration layers”

Layer 1 — MCP server (read access)

Section titled “Layer 1 — MCP server (read access)”

The MCP server at POST /v1/mcp exposes Vauchflow tools over HTTP JSON-RPC 2.0 to any agent that supports the Model Context Protocol. There is no separate package or sidecar — the server runs inside the Vauchflow API JAR and shares the same tenant isolation and rate limiting as the REST API.

Who it is for: developers using Claude Desktop, Cursor, Windsurf, or custom MCP clients.

Paste this into your Claude Desktop config to connect:

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

See MCP server for the full tool reference, required scopes, and error envelope.

Layer 2 — Custom GPT (read + safe writes)

Section titled “Layer 2 — Custom GPT (read + safe writes)”

The Vauchflow Promotions Assistant is a Custom GPT that lets marketers and operations users query campaigns, validate voucher codes, and review redemption analytics in plain English — no code required. (Listing pending — search “Vauchflow Promotions Assistant” once published in the OpenAI GPT Store.)

Who it is for: non-technical marketing and ops users working inside ChatGPT.

When the GPT prompts for an API key, create a vf_ak_* agent key with scopes VOUCHER_READ, VOUCHER_VALIDATE, CAMPAIGN_READ, and ANALYTICS_READ. Write operations return a friendly refusal — they are not forwarded to the API.

See AI agents — Custom GPT for setup details.

Architecture

Section titled “Architecture”
┌──────────────┐    ┌──────────────────┐    ┌───────────────┐
│ Claude / GPT │ ─► │ /v1/mcp endpoint │ ─► │ vf_ak_* auth  │
└──────────────┘    └──────────────────┘    └──────┬────────┘
                                                    │
┌──────────────┐    ┌────────────────────┐   ┌─────▼─────────┐
│  Operator    │ ◄─ │ Approval queue UI  │ ◄─│  Risk policy  │
│  dashboard   │    │ (high-risk writes) │   │  evaluator    │
└──────┬───────┘    └────────────────────┘   └───────────────┘
       │
┌──────▼───────┐    ┌──────────────┐    ┌───────────────────┐
│  Use-case    │ ─► │   Outbox     │ ─► │  agent.action.*   │
│  (execute)   │    │   (relay)    │    │  webhook events   │
└──────────────┘    └──────────────┘    └───────────────────┘

The approval queue sits between the agent key auth layer and the use-case execution layer. Low-risk reads (validate a voucher, list campaigns, fetch analytics) pass through immediately. High-risk writes (create campaign, bulk voucher generation > 100, webhook config changes) are held pending operator review.

Safety primitives

Section titled “Safety primitives”
  • Atomic redemption guaranteed by single-SQL UPDATE — verified by 100-thread load test.
  • Scoped vf_ak_* agent keys with per-tool grants — an agent key for read operations cannot create campaigns
  • Operator approval queue for high-risk writes: campaign creation, bulk voucher generation > 100, webhook config changes
  • Dry-run preview header (Vauchflow-Dry-Run: true) returns what would happen without executing the write
  • Audit context header (Vauchflow-Agent-Context) for non-PII fingerprinting of agent requests
  • agent.action.* webhook events for end-to-end auditability of every agent action lifecycle
  • Designed for teams who want AI agents to drive promotions but need procurement, audit, and operator-in-the-loop guarantees by default