spawnpop MCP server docs

What it is

spawnpop makes Roblox game assets: a GUI set, icons, a thumbnail, 3D props and music. The MCP server lets an agent do that on a person's behalf. It plans a kit from one sentence, tells the agent the credit price, makes cheap drafts, generates the finals the person approved, and hands back signed download links plus the next calls for Roblox Studio. For the product side, see the connect page and pricing.

Get a key

1. Open spawnpop.com/mcp and choose Connect. A key is created after a first credit purchase, because a key is how an agent spends credits. Buying as a guest works; you do not need an account.
2. The key starts with sp_live and is shown once. Copy it straight into an environment variable named SPAWNPOP_API_KEY.
3. Choose a read key (can call get_status, get_files and list_projects) or a read and generate key (can also plan, draft, approve and spend credits). Pick read-only for dashboards and monitoring agents.
4. An account holds up to 3 keys. Revoke any of them in Settings, API keys; a revoked key stops working at once.

Never commit a key. Put it in an environment variable or a secret store and reference it from the config, as in the snippets below. Keys are stored hashed, so a lost key cannot be shown again; create a new one.

Set up your agent

Set SPAWNPOP_API_KEY in your shell first, then add the server. Each snippet reads the key from the environment, so the key is not written into a file.

claude mcp add --transport http spawnpop https://spawnpop.com/mcp --header "Authorization: Bearer $SPAWNPOP_API_KEY"

# ~/.codex/config.toml
[mcp_servers.spawnpop]
url = "https://spawnpop.com/mcp"
bearer_token_env_var = "SPAWNPOP_API_KEY"

{
  "mcpServers": {
    "spawnpop": {
      "url": "https://spawnpop.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SPAWNPOP_API_KEY}"
      }
    }
  }
}

export SPAWNPOP_API_KEY=<your key>   # created on /mcp

# 1. initialize
curl -s https://spawnpop.com/mcp \
  -H "Authorization: Bearer $SPAWNPOP_API_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-agent","version":"0.1"}}}'

# 2. list the tools
curl -s https://spawnpop.com/mcp \
  -H "Authorization: Bearer $SPAWNPOP_API_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. call one (plan_kit also works without the Authorization header)
curl -s https://spawnpop.com/mcp \
  -H "Authorization: Bearer $SPAWNPOP_API_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"plan_kit","arguments":{"description":"a candy pet collecting simulator","genre":"simulator"}}}'

Claude Desktop is not supported yet because it requires OAuth sign-in, which this server does not offer. Any client that can send a bearer header to a Streamable HTTP server works. After connecting, ask the agent to run tools/list; it should see the seven tools below.

Tool reference

All tools return both readable text and a structuredContent object. The tables list the fields of that object. The server also sends short instructions in the initialize reply that summarise the workflow, so a well-behaved client already shows them to the model.

The agent workflow

The recommended order keeps the human informed and the spend small:

1. plan_kit with the game idea. Show the human the items and totalCredits.
2. draft the items for 10 credits per draft image. Each draft comes with an AI fit verdict.
3. get_status with waitSeconds 25 until the drafts are ready. Show the human the draft URLs.
4. approve the drafts that fit. No charge.
5. generate with itemIds "approved", the confirmed price and a new requestId.
6. get_status again until done is true, then get_files.
7. Import into Roblox Studio (see below).

Worked example

A person asks for a candy pet simulator. The totals below are computed from the live price list, so they stay correct if prices change. Responses are trimmed to the interesting fields. Ids such as proj_8f3k2 are examples.

{
  "name": "plan_kit",
  "arguments": {
    "description": "a candy pet collecting simulator",
    "genre": "simulator",
    "style": "chunky pastel cartoon"
  }
}

{
  "projectId": "proj_8f3k2",
  "genre": "simulator",
  "theme": {
    "palette": [
      "#ff8fb1",
      "#ffd36e",
      "#7ad7c1"
    ],
    "currency": "Candy",
    "motifs": [
      "lollipops",
      "striped awnings"
    ]
  },
  "items": [
    {
      "id": "gui-kit",
      "name": "Candy GUI set",
      "assetType": "gui_set",
      "count": 1,
      "credits": 120,
      "generatable": true,
      "draftable": true
    },
    {
      "id": "game-icon",
      "name": "Game icon",
      "assetType": "game_icon",
      "count": 1,
      "credits": 40,
      "generatable": true,
      "draftable": true
    },
    {
      "id": "pets",
      "name": "Pet props",
      "assetType": "prop_3d",
      "count": 2,
      "credits": 160,
      "generatable": true,
      "draftable": true
    }
  ],
  "totalCredits": 320,
  "balance": 150,
  "canAfford": false,
  "payUrl": "https://spawnpop.com/mcp/pay?t=<token>"
}

The kit costs 320 credits and the plan shows that the balance is lower. Drafts are cheap, so the agent drafts first.

{
  "name": "draft",
  "arguments": {
    "projectId": "proj_8f3k2",
    "itemIds": [
      "gui-kit",
      "game-icon",
      "pets"
    ],
    "variants": 1,
    "confirmCredits": 40,
    "requestId": "candy-drafts-001"
  }
}

{
  "jobIds": [
    "job_a1",
    "job_a2",
    "job_a3",
    "job_a4"
  ],
  "creditsCharged": 40,
  "balance": 110
}

{
  "items": [
    {
      "itemId": "gui-kit",
      "name": "Candy GUI set",
      "assetType": "gui_set",
      "status": "drafted",
      "copies": 1,
      "note": "Draft ready; approve it, then generate"
    }
  ],
  "drafts": [
    {
      "itemId": "gui-kit",
      "copy": 0,
      "outputId": "out_77",
      "status": "succeeded",
      "verdict": "fit",
      "reasons": [],
      "url": "https://spawnpop.com/api/assets/dl/out_77?u=...&exp=...&sig=..."
    }
  ],
  "summary": {
    "succeeded": 0,
    "failed": 0,
    "running": 0,
    "mixed": false
  },
  "balance": 110,
  "done": false
}

{
  "name": "approve",
  "arguments": {
    "projectId": "proj_8f3k2",
    "approvals": [
      {
        "itemId": "gui-kit",
        "copy": 0,
        "outputId": "out_77"
      }
    ]
  }
}

{
  "name": "generate",
  "arguments": {
    "projectId": "proj_8f3k2",
    "itemIds": "approved",
    "confirmCredits": 120,
    "requestId": "candy-final-001"
  }
}

The balance is a little short for the GUI set, so the call is refused before anything is charged:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Not enough credits: needs 120, balance 110. Show the user payUrl; after payment retry this exact call with the same requestId."
    }
  ],
  "structuredContent": {
    "code": "insufficient_credits",
    "message": "Not enough credits: needs 120, balance 110. Show the user payUrl; after payment retry this exact call with the same requestId.",
    "needed": 120,
    "balance": 110,
    "shortfall": 10,
    "payUrl": "https://spawnpop.com/mcp/pay?t=<token>",
    "messageForUser": "This needs 120 credits and the account has 110. Open https://spawnpop.com/mcp/pay?t=<token> to add credits (no sign-up needed), then tell me to continue."
  }
}

The agent shows messageForUser to the human, who opens the link and pays. The agent then repeats step 5 unchanged, with the same requestId:

{
  "jobIds": [
    "job_b1"
  ],
  "creditsCharged": 120,
  "skipped": [],
  "balance": 310,
  "replayed": false
}

{
  "files": [
    {
      "itemId": "gui-kit",
      "assetType": "gui_set",
      "name": "buy-button.png",
      "kind": "element",
      "url": "https://spawnpop.com/api/assets/dl/out_91?u=...&exp=...&sig=...",
      "bytes": 48211,
      "width": 512,
      "height": 256
    }
  ],
  "roblox": {
    "uploadImages": {
      "tool": "upload_image",
      "urls": [
        "https://spawnpop.com/api/assets/dl/out_91?..."
      ]
    },
    "luau": "-- builds a ScreenGui from the ids you fill in",
    "models": [],
    "audio": null,
    "safety": "Set ROBLOX_API_KEY in your own shell."
  }
}

Credits and payments for agents

Credits are bought in advance, never expire, and failed generations are refunded to the balance. The rules an agent must follow:

• confirmCredits. Every spending call (draft, generate) must carry the exact price. Compute it from the credits field of the plan items, and show it to the human first.
• requestId. A string of 8 to 64 letters, digits, _ or -. The same requestId returns the same jobs and charges nothing the second time, so retry freely after a timeout or after the human has paid. Use a new one for each new purchase, including a retry of items that failed.
• insufficient_credits. Nothing is charged. The result carries needed, balance, shortfall, payUrl and messageForUser. Give the message to the human, wait for them to say they have paid, then repeat the exact same call. The link works without an account and expires after 24 hours.
• price_changed. If the price moved between your plan and your call, nothing is charged and totalCredits holds the new price. Show it to the human and call again with the new value.
• Refunds. A job that fails is refunded automatically; get_status shows it as failed. See the refund policy.

Prices

The tool results always carry the current price, so read it from there instead of copying this table into your agent. The pricing page lists the credit packs.

Rate limits

Limits use fixed windows, and retryAfterSeconds is the time until the window ends. When a provider is briefly unavailable the result has code provider, refunded true and a retryAfterSeconds; wait that long and retry.

Errors

Tool failures come back as a normal result with isError true and a structuredContent.code. Authentication and transport problems are HTTP statuses. Malformed JSON-RPC gets a JSON-RPC error object.

Using the files in Roblox Studio

get_files returns a roblox block so the agent does not have to guess. In Roblox Studio, open Assistant, then Manage MCP Servers, and enable Studio as an MCP server; add it to the same agent that has spawnpop.

1. Images. Pass roblox.uploadImages.urls to Studio's upload_image tool. The URLs are valid for 60 minutes. Each upload gives an asset id.
2. Place them. Fill the ids into the Luau script from roblox.luau and run it with execute_luau in Edit mode. It builds a ScreenGui in StarterGui:

-- Run with execute_luau in Edit mode, after filling the ids from upload_image.
local ids = {
  ["buy-button.png"] = "rbxassetid://REPLACE_WITH_ID_FOR_BUY_BUTTON_PNG",
}
local gui = Instance.new("ScreenGui")
gui.Name = "SpawnpopKit"
gui.ResetOnSpawn = false
local frame = Instance.new("Frame")
frame.Size = UDim2.fromScale(1, 1)
frame.BackgroundTransparency = 1
frame.Parent = gui
local grid = Instance.new("UIGridLayout")
grid.CellSize = UDim2.fromOffset(96, 96)
grid.Parent = frame
for name, id in pairs(ids) do
  local label = Instance.new("ImageLabel")
  label.Name = name
  label.Image = id
  label.BackgroundTransparency = 1
  label.ScaleType = Enum.ScaleType.Fit
  label.Parent = frame
end
gui.Parent = game:GetService("StarterGui")

3. 3D models and audio. These go through Roblox Open Cloud. The user runs the curl commands from roblox.models in their own terminal with their own key:

# Keep the key in your own shell. Never paste it into an AI chat.
export ROBLOX_API_KEY=...        # created in the Roblox Creator Hub, scoped to asset upload
export ROBLOX_USER_ID=...        # the creator account that will own the asset

curl -L -o "pet.glb" "<url from get_files>"
curl -X POST "https://apis.roblox.com/assets/v1/assets" -H "x-api-key: $ROBLOX_API_KEY" \
  -F 'request={"assetType":"Model","displayName":"pet","description":"Made with spawnpop","creationContext":{"creator":{"userId":"'"$ROBLOX_USER_ID"'"}}};type=application/json' \
  -F "fileContent=@pet.glb;type=model/gltf-binary"
# The reply holds an operation path. Poll GET https://apis.roblox.com/assets/v1/operations/<id> until done, then read assetId.

Never paste your Roblox API key into an AI chat, and never send it to spawnpop. spawnpop does not ask for one. Keep it in $ROBLOX_API_KEY in your own shell. Roblox sets its own limits and review rules for uploaded audio and models; check them in the Creator Hub before you upload.

FAQ

More questions? See help, security or the GUI generator for what the assets look like. The genres you can pass to plan_kit are simulator, tycoon, tower_defense, obby, rng, horror, roleplay, fighting.