Create a project with MCP or API

Create with your agent#

Connect your client to https://mockspace.ynext.co/mcp and complete OAuth sign-in. Call list_projects to check for an existing project, then call create_project:

{
  "project": "my-app",
  "repo": "owner/repository",
  "workspace": "apps/web",
  "description": "Help customers plan their next trip"
}

These tools work before you have a published review. Creation registers a persistent project and returns its workspace URL and setup instructions. The agent uses its own repository access and local tools to prepare and capture the app, then publishes a review. The server does not clone repositories or start an agent when you register a project.

The New project page provides connection commands and a complete agent prompt.

Create through the API#

Send POST https://mockspace.ynext.co/api/projects with Content-Type: application/json and the same JSON object. Authenticate with Authorization: Bearer <token> or x-mockspace-token. OAuth access tokens, personal tokens, and configured machine tokens are accepted. A browser session cookie alone is not accepted for creation.

| Field | Meaning | | --- | --- | | project | Required unique slug. 1–64 lowercase letters, numbers, or hyphens; start and end with a letter or number. Site route names are reserved. | | repo | Optional GitHub owner/name; no credentials or URLs. | | workspace | Relative app directory, such as apps/web. Defaults to .. Parent-directory traversal is rejected. | | description | Optional description, up to 500 characters. |

Ownership comes from the authenticated token. Do not send an owner field. The request body is limited to 8 KB.

curl --fail-with-body https://mockspace.ynext.co/api/projects \
  -H "Authorization: Bearer $MOCKSPACE_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"project":"my-app","repo":"owner/repository","workspace":"."}'

A successful response includes created, project metadata, url, and next.guide and next.instruction. The Location header contains the workspace URL. GET /api/projects and MCP list_projects include your registered projects even when their latest build is null.

| Status | What to do | | --- | --- | | 201 | Project created. Follow the returned setup instructions. | | 200 | Your identical request already created this project. Reuse the returned URL. | | 400 | Correct the field named in the error. Unknown fields are rejected. | | 401 | Authenticate with a valid token. An expired token requires sign-in again. | | 409 | Choose another name if it is already in use. If creation is still in progress, retry the same details. | | 413 / 415 | Reduce the body to 8 KB or send JSON with the correct content type. | | 429 | Wait before retrying; REST responses include Retry-After. |

Publish the first review#

Use mockspace publish --as <registered-slug> to publish into the registered project while preserving the name in existing local configuration. Follow the agent guide to capture and validate the app, then publish with an authenticated CLI login or automation credential.

Before the first publish, the registration appears only to its creator and machine administrators, or on a deployment without sign-in. Published builds continue to use the existing per-build visibility rules. Registering a project does not grant exclusive publishing rights or change the deployment's sharing policy.

Read Authentication and visibility for credential setup. The hosted MCP uses OAuth; the REST API also supports personal and machine credentials.