# Create a project

## Before you start

- A Bastide account and an organization where you hold at least the maintainer role (`maintainer`): it is the rank `project_create_with_backend` requires.
- A Git repository reachable at the address you will give Bastide.
- A token for your agent, issued from the console: you choose its scopes (read only, deploy, administer). It is revoked with one click.

## 1. Connect your agent

In Claude Code, replace the address with the one the console shows for your organization:

```
claude mcp add --transport http bastide <your-organization-mcp-address> --header "Authorization: Bearer <your-token>"
```

On first contact the agent lists the available tools. The full catalogue, with the schema of every entry, is in [mcp-tools.json](../mcp-tools.json).

## 2. Find the organization

The `account.organization.list` operation returns the organizations where the account holds a role: identifier (`org_...`), slug, name and roles. It touches the identity of the account: it is not an MCP tool, and is read through the HTTP API, under a personal token.

```
curl -H "Authorization: Bearer <your-token>" https://api.bastide.fr/v1/account/organizations
```

Keep the identifier of the organization that will own the project, and give it to your agent.

## 3. Create the project, its database and the first deployment

The `project_create_with_backend` tool does all three in one call.

| Field | Required | Meaning |
| --- | --- | --- |
| `organizationId` | yes | The `org_...` identifier from step 2. |
| `slug` | yes | Readable identifier, lowercase letters, digits and hyphens, unique. |
| `name` | yes | Display name, 1 to 120 characters. |
| `gitRemote` | no | Address of the Git repository. |
| `ref` | no | Branch, tag or commit to build; by default, the default branch. |
| `idempotencyKey` | no | 8 to 128 characters: replaying the call with the same key does not create a second project. |

Example arguments:

```json
{
  "organizationId": "org_01JQ8ZK4M7NP2RSTVWXYZ34567",
  "slug": "my-shop",
  "name": "My shop",
  "gitRemote": "https://example.org/my-shop.git",
  "idempotencyKey": "create-my-shop-001"
}
```

The response carries the project, the `environmentId` of its production, the deployment that was started and a `suivi` list that says what to read next. Keep `project` and `environmentId`: [deploying](deploy.md) and [restoring](restore.md) need them.

To create only the project, without its database or deployment, use `project_create`.

## When it fails

A refusal returns a precise error code and what to do next, never a bare HTTP code. The codes of each tool are in [the MCP reference](../reference/en/mcp.md). The refusals specific to this creation are `plafond_de_creations_de_projet` (five creations per rolling day through agents) and `palier_choisi_par_une_personne`: an agent creates a project at the default tier, which is why the `tier` field is left out; the tier, which commits spending, is chosen by a person.

See also: [Deploy](deploy.md).