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 project. The project can start empty or use code from GitHub or a ZIP archive.

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.

3. Select source code

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

  1. 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

For a public repository, pass its name in owner/repository format.

For a private repository, first connect the GitHub account in AppWizzy. That account must have access to the repository.

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. Pass the archive upload ID to create_project.

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

4. 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.

create_project reserves the required credits and starts project creation. Review the quote before you allow this paid action.

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.

5. 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.

Common creation errors

Error What to do
INSUFFICIENT_CREDITS Add credits, then request a fresh quote
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 Call check_project_creation again
PRICE_CHANGED Request and review a new quote
GITHUB_NOT_CONNECTED Connect GitHub in AppWizzy before the import
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
ARCHIVE_UPLOAD_NOT_READY Complete the PUT upload, then retry with the same idempotency key
PROVISIONING_UNAVAILABLE Retry with the same idempotency key

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.