How to run a giveaway with an AI agent

Updated 10 November 2026 · By the Vast team

An AI agent such as Claude Code, Claude, Cursor or Codex can draft a Vast giveaway for you, add the entry actions, check it's ready, and report entries once it's live. It connects to Vast's MCP server with an API key you create, and it can only do what that key allows. The agent drafts. You decide when the giveaway goes public.

Today, API keys for agents need a paid plan.

Vast is our product, so weigh that. Setup steps for other tools come from their own docs, checked on November 10, 2026. Vast details come from our help center, our public plugin repo and the code behind the agent API.

What MCP is

MCP, the Model Context Protocol, is an open standard for connecting AI apps to outside tools and data. The MCP docs compare it to "a USB-C port for AI applications." A service runs an MCP server that offers tools, such as "create a giveaway draft," and your agent app is the client that calls them when you ask. Vast's server lives at https://general.vast.gg/mcp and speaks Streamable HTTP. Every request carries your API key, so the server knows whose giveaways the agent can touch and what it's allowed to do.

Before you start

You need two things: a Vast account on a paid plan, and an API key. Our plans guide compares the plans, and the plans page has current prices.

To create a key, open Settings, then Developer. Give the key a name, choose what it can do under Access, and choose when it expires: 7, 30, 90 or 365 days. Copy the key when it appears, because Vast only shows it once.

Access optionWhat the agent can doWhen you need it
Read giveawaysSee your plan limits, your giveaways and the entry action typesTo check limits and drafts (on by default)
Create and edit draftsCreate drafts, add entry actions, change draftsTo build a giveaway (on by default)
Publish giveawaysPublish a draft when you askOnly if you want the agent to take it live
Entry statsRead views, entrants, entries and completions per actionTo report results
WinnersRead winners after the draw, as rank and masked usernameTo report winners, together with Entry stats

Keep the key in an environment variable called VAST_API_KEY, and never paste it into a chat:

export VAST_API_KEY="vast_sk_..."

Set up your agent

Pick the path that matches your tool. All of them end up talking to the same server.

claude plugin marketplace add Firstbloodio/vast-giveaways
claude plugin install vast-giveaways@vast

The plugin adds Vast's MCP server and a skill that walks the agent from draft to launch. Its server config reads the key from VAST_API_KEY, so set that before you start Claude Code. Anthropic's plugin docs cover install scopes and how to update or remove a plugin.

Cursor, Codex and other agents: the skill

npx skills add Firstbloodio/vast-giveaways

This uses skills, an open-source command-line tool from Vercel. skills.sh lists Claude Code, Cursor, Codex, GitHub Copilot, Windsurf and Gemini among the agents it supports. The skill teaches your agent the steps and the rules. It doesn't connect to Vast by itself, so add the server too, as below.

The raw MCP config

For Claude Code without the plugin, one command adds the server:

claude mcp add --transport http vast https://general.vast.gg/mcp --header "Authorization: Bearer $VAST_API_KEY"

Your shell fills in the key when you run it, so Claude Code saves the key in its own settings. To keep the key out of every file, use a project .mcp.json instead. Claude Code's MCP docs say it expands environment variables such as ${VAST_API_KEY} in that file:

{
  "mcpServers": {
    "vast": {
      "type": "http",
      "url": "https://general.vast.gg/mcp",
      "headers": { "Authorization": "Bearer ${VAST_API_KEY}" }
    }
  }
}

Cursor. Put the server in .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project. Cursor's MCP docs use ${env:NAME} for environment variables:

{
  "mcpServers": {
    "vast": {
      "url": "https://general.vast.gg/mcp",
      "headers": { "Authorization": "Bearer ${env:VAST_API_KEY}" }
    }
  }
}

Codex. Add this to ~/.codex/config.toml. The Codex MCP docs say bearer_token_env_var names the variable that holds the token, and that the Codex CLI and IDE extension share this file:

[mcp_servers.vast]
url = "https://general.vast.gg/mcp"
bearer_token_env_var = "VAST_API_KEY"

Claude (web and desktop). Add a custom connector with the server address. Anthropic's connector guide says the Request headers field takes "fixed credentials such as API keys," so add an Authorization header with the value Bearer and your key. Here Claude stores the key, not an environment variable. Claude's own Free plan allows one custom connector.

Any other MCP client that supports Streamable HTTP uses the same address and the same Authorization header.

To check that the key works before you involve an agent:

curl -H "Authorization: Bearer $VAST_API_KEY" https://general.vast.gg/agent/v1/me

An example prompt

"Draft a one-week giveaway for a $50 Steam gift card, two winners, starting Monday at 9:00 New York time. To enter, people follow @yourstudio on X, follow yourstudio on Twitch, and wishlist our game on Steam. Don't publish it yet."

Give the agent the prize and its value, the number of winners, the dates with a time zone, and the actions. If something is missing, the skill tells the agent to ask rather than make it up.

What the agent does, step by step

  1. Checks your plan with get_my_plan_limits: giveaways left this month, the prize and winner limits, and the key's access and expiry.
  2. Looks for duplicates with list_my_giveaways, so it doesn't draft a giveaway you already have.
  3. Reads the action list with list_action_types. It returns the entry actions a key can add, their fields, and the kinds you have to set up in the web editor. In the example, the X and Twitch follows are allowed and the Steam wishlist isn't.
  4. Creates the draft with create_giveaway_draft. It sends an idempotency key, so a retry returns the same draft instead of a second one. Drafts count toward your giveaways for the month.
  5. Adds and fixes with add_entry_actions, up to 10 actions per call, and update_giveaway_draft. Vast rewrites the official rules to match each change.
  6. Previews with preview_giveaway, fixes the problems it lists, and shows you a summary: title, prize, dates, actions, and links to the draft and the editor.
  7. Stops and waits. It publishes only when you say so, and only if the key has the Publish giveaways access.
  8. Reports results later with get_entry_stats: views, unique entrants, total entries and completions per action. With the Winners access, it also lists winners after the draw.

The skill ends every session with a short action plan of what's done and what only you can do. For the example prompt, it would look something like this:

What stays with you

Safety

Limits

LimitToday
PlanToday, API keys for agents need a paid plan
Actions an agent can addLog in to Vast, Visit a page, Follow on X, Repost on X, Visit a YouTube channel, Visit an Instagram profile, Visit a Facebook page, Follow on TikTok, Twitch, Kick or Bluesky, and Bonus
Actions per callUp to 10
EditingDrafts only
PublishingUp to 10 publishes an hour per account
Requests120 a minute per key, 300 a minute per account, and 30 changes a minute per key
KeysUp to 10 active, each expiring after 7 to 365 days
Monthly giveawaysDrafts count, the same as in the web editor

Checks work the same as in the web editor. Vast checks Twitch follows against the player's connected Twitch account. It doesn't check X, Discord or Kick actions automatically today, so look over winners before you announce them.

FAQ

Do I need a paid plan? Yes. Today, API keys for agents need a paid plan. Any paid plan works.

Can the agent publish without asking me? Publishing needs the Publish giveaways access and an explicit confirmation, and the skill tells the agent to publish only when you ask. To be certain, create the key without that access.

Can the agent add a Steam wishlist or Discord join action? Not today. It adds the actions a key supports and lists the rest for you to finish in the web editor.

Which agents work? Claude Code, Claude, Cursor and Codex, plus any MCP client that supports Streamable HTTP and lets you set an Authorization header.

Can the agent see who entered? It sees counts per action, not entrants' emails. With the Winners access, it sees winners as a rank and a masked username. You see winners' emails in Vast, so you can deliver prizes.

Create an API key and connect your agent in a few minutes. Read the setup steps

Sources

More guides