Create Projects with AppWizzy MCP

Applies to: AppWizzy Projects MCP with projects:create

AppWizzy Projects MCP uses a validate-then-create process. The client first finds eligible machine sizes and requests a short-lived credit quote.

The client must pass that quote to create_project before AppWizzy creates the project.

The current process creates an AppWizzy External Code development environment. You can import GitHub or ZIP code, or explicitly choose an empty project. For all three options, create_project automatically starts AI setup and launch.

Before you begin

Connect and authorize the MCP server for AppWizzy Projects MCP. Follow Connect to AppWizzy with MCP.

For the full workflow, authorize:

  • projects:read finds machine sizes, lists projects, and reads project creation status.
  • projects:create validates, quotes, uploads, and creates.

Your AppWizzy credit balance must have enough credits. Your account must allow the requested project visibility.

1. List eligible machines

Call list_project_machines before you validate a project. It returns only machine sizes that support the External Code template.

The result gives you:

  • machine slug and display name.
  • CPU and RAM.
  • credits per 24-hour hosting period.
  • estimated monthly credits.
  • the recommended option.

Use the returned machine slug in later calls. Do not invent a machine slug.

Do not use a machine slug from an old catalog response.

2. Check the project and obtain a quote

Call check_project_creation with these values:

  • name: 1–50 characters.
  • project_description: 1–24,000 characters.
  • machine_slug: a slug that list_project_machines returned.
  • visibility: public or private.

This call does not create a project. It does not charge your AppWizzy credit balance.

The call checks:

  • machine eligibility.
  • available credits in your AppWizzy credit balance.
  • project limits.
  • private-project entitlement.

If the request is valid, the call returns:

  • the effective machine slug.
  • the estimated credit cost for the first 24-hour hosting period.
  • a signed quote token.
  • a quote expiry time.

The quote is valid for five minutes. Request a new quote if it expires or the machine size price changes.

Require allowed=true before creation. A quote does not establish your consent to a paid action.

The estimated_credit_cost is the hosting price reserved for the first 24-hour period. The quote excludes separately charged AI usage and is not a final project total.

3. Select source code

You can create the project in one of these three ways:

  1. Explicitly choose to start without an imported code base.
  2. Pass github_repository in owner/repository format.
  3. Upload a ZIP archive and pass its archive_upload_id.

Do not supply both GitHub and ZIP sources in the same request.

Import from GitHub

First connect your GitHub account in AppWizzy. This requirement applies to public and private repositories.

The connected account must have access to the repository. Pass its name in owner/repository format.

Import a ZIP archive

Call prepare_project_archive_upload with a filename that ends in .zip. The call returns:

  • a one-time HTTPS upload URL.
  • an upload bearer token.
  • an archive upload ID.
  • the expiry time.
  • the maximum upload size.

The current upload limit is 100 MB. The prepared upload is valid for 30 minutes.

Upload the ZIP with HTTP PUT. Use the returned bearer token and Content-Type: application/zip.

A successful upload returns HTTP 204. Keep the archive upload ID for creation after you approve the terms below.

Upload success does not authorize paid creation.

The upload URL is separate from the MCP JSON-RPC endpoint. Never put the upload bearer token in a prompt, repository, or log.

Before creation, your agent must show:

  • the effective machine and its current daily credit rate.
  • the GitHub repository, uploaded ZIP, or your explicit choice of an empty project.
  • project visibility.
  • credits reserved for the first 24-hour period.
  • the ongoing daily credit rate for later periods.
  • automatic AI setup and launch, with AI usage charged separately from hosting.

The quote and monthly catalog figure cover hosting only. AppWizzy charges AI usage separately in AppWizzy credits. The final AI cost depends on actual usage and is unknown before creation. The agent must not promise a fixed AI cost or combined total.

Give explicit consent to these parameters, hosting costs, and additional AI usage charges. The agent must explain both cost components and wait for your consent before it calls create_project.

If you refuse, the agent must not call create_project. Your refusal must not create a project or credit reservation.

Changed parameters, changed prices, or an expired quote before creation require a new allowed quote.

Review the new terms and give fresh consent before creation. Your earlier consent does not approve changed terms.

5. Create with an idempotency key

Call create_project with the same validated name, description, machine size, and visibility. Also provide:

  • the quote token.
  • one UUID idempotency key for this project intent.
  • either the optional GitHub repository or ZIP upload ID.

After your consent, create_project reserves the hosting credits and starts project creation. AppWizzy automatically starts AI setup and launch as part of this process.

If the request times out or returns a retryable error, use the same idempotency key for the retry.

The same key prevents a duplicate project and a duplicate credit reservation for the same intent.

Use a new idempotency key only when:

  • the previous operation has a terminal failed state.
  • you intentionally start a different project request.

Never reuse an idempotency key with different project inputs.

6. Monitor provisioning

The create_project response includes:

  • operation_id.
  • project_uuid.
  • current status.
  • whether the MCP server found a duplicate request.
  • the AppWizzy project URL.

With projects:read, call get_project_status with the operation ID. The public operation states are:

  • queued.
  • provisioning.
  • ready.
  • blocked.
  • failed.
  • expired.

Do not submit a new creation request because provisioning is queued or provisioning.

ready means the development VM service and required repository preparation or code import are complete.

This status does not verify that your application runs or responds at a production URL.

The returned project_url opens your AppWizzy project page at /projects/:uuid. It is not the application URL.

For blocked, read the status message before you act. Ask support to review an uncertain operation before another creation attempt.

For failed, keep the operation ID and status message. Resolve the cause before a new attempt with fresh consent.

Common creation errors

Error What to do
INSUFFICIENT_CREDITS Add credits, request a fresh quote, and approve the terms before creation
PROJECT_LIMIT_REACHED Review the account project limit or remove an unneeded project
PRIVATE_PROJECT_NOT_ALLOWED Choose public visibility or use a plan that permits private projects
MACHINE_UNAVAILABLE Call list_project_machines again and select a returned machine
QUOTE_EXPIRED Request a new allowed quote and give fresh consent before creation
PRICE_CHANGED Request a new allowed quote and approve the new price before creation
GITHUB_NOT_CONNECTED Connect GitHub in AppWizzy for public or private repository imports
GITHUB_REPOSITORY_UNAVAILABLE Confirm the connected account can access the repository
MULTIPLE_CODE_SOURCES Choose GitHub or ZIP, not both
ARCHIVE_UPLOAD_EXPIRED Prepare and upload the ZIP again. Obtain a valid quote and fresh consent before creation
ARCHIVE_UPLOAD_NOT_READY Complete the PUT upload, then retry with the same idempotency key
PROVISIONING_UNAVAILABLE Retry with the same idempotency key
IDEMPOTENCY_CONFLICT Use the original inputs for a retry. Use a new key for an intentional different project

For an unexpected error, keep the returned correlation ID. Give it to AppWizzy support.

Do not send OAuth tokens, upload tokens, GitHub credentials, or provider keys.

Protocol and request limits

  • The MCP endpoint accepts JSON requests through remote Streamable HTTP.
  • Each authenticated connection has a limit of 120 requests per minute.
  • The MCP JSON request body has a limit of 64 KB.
  • The MCP endpoint does not support JSON-RPC batch requests.
  • ZIP archive content uses the separate one-time upload URL.
  • The client does not send ZIP archive content in the MCP request body.