create_project

Purpose

Scaffold a new project. Enforces the creator tier's project limit, handle uniqueness and the tier-level custom_handle capability before the row lands. A project has no platform of its own: install connectors on it afterwards with install_connector.

Required ability

project:create

Input schema

{
  "type": "object",
  "required": ["name"],
  "properties": {
    "name": { "type": "string", "minLength": 5, "maxLength": 255 },
    "description": {
      "type": "string",
      "maxLength": 1000,
      "description": "HTML is filtered to a safe subset before storage."
    },
    "handle": {
      "type": "string",
      "pattern": "^[a-z0-9-]{5,255}$",
      "description": "Requires Starter / Growth tier (custom_handle capability). Free tier tokens receive TEAM_TIER_REQUIRED when a handle is supplied."
    },
    "terms": { "type": "string", "format": "uri", "maxLength": 255 },
    "privacy": { "type": "string", "format": "uri", "maxLength": 255 },
    "metrics": { "type": "boolean" },
    "active": {
      "type": "boolean",
      "description": "Defaults to true. Set false to create in draft state."
    },
    "team_id": {
      "type": "string",
      "description": "UUID of the owning team. Defaults to the token's scoped team."
    }
  }
}

banner and photo are not MCP inputs. Banner + avatar are uploaded as multipart image files via the REST API or through the creator dashboard so the server can resize and host them on S3 — MCP clients have no multipart channel, so they can create a project without artwork and add it later through either of those paths.

Output shape

{
  "data": {
    "id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "name": "Research Premium",
    "handle": "research-premium-abc123",
    "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",
    "active": true,
    "created_at": "2026-05-18T10:05:00Z"
  }
}

Example prompts

"Create a Subscriby project called 'Research Premium'."

"Scaffold a project with handle 'weekend-deep-dives' and a one-paragraph description." (requires Starter+ tier)

Failure modes

TEAM_TIER_REQUIRED — creator has hit their plan's project limit, or they passed a handle while on a tier that does not include custom_handle. Error context carries required_capability.
VALIDATION_FAILED — name too short, handle malformed / taken, or team_id is a team the token's owner does not belong to.