# Connect your AI tool to builders.zone

builders.zone runs an MCP server for cohort members. Once your AI tool is connected it can read the cohort path, open any guide or prompt, search all guide text and tick off your progress.

Server address: `https://builders.zone/api/mcp` (Streamable HTTP).

Sign-in always goes through your own builders.zone account: desktop tools open the builders.zone sign-in page, and cloud agents use a personal token you create while signed in. You need a cohort seat.

## Agents: how to connect

If a person asks you to connect to the builders.zone MCP, add `https://builders.zone/api/mcp` as a remote HTTP MCP server in your own tool using the steps below, then ask them to sign in when the browser opens. If you run in the cloud and can't open a browser, ask them to create a token at https://builders.zone/app/settings/assistant and store it as `BUILDERS_ZONE_TOKEN`. Once connected, run the `start` prompt or call `bz_cohort_path`.

## On your computer (sign in through the browser)

### Claude (claude.ai, desktop and mobile)

1. Open **Settings → Connectors → Add custom connector**.
2. Name it `builders.zone` and paste `https://builders.zone/api/mcp`.
3. Click **Connect**, sign in to builders.zone and click **Allow**.

### Claude Code (terminal, VS Code, JetBrains)

1. Run the command below once. (The cohort boilerplate already includes it in `.mcp.json`, so inside that project you can skip this.)
2. In Claude Code type `/mcp`, pick `builders-zone` and sign in in the browser window that opens.
3. Type `/builders-zone:start` (or say "start builders.zone").

Terminal:

```bash
claude mcp add --transport http --scope user builders-zone https://builders.zone/api/mcp
```

### Cursor (desktop app)

1. Open **Cursor Settings → Tools & MCP → New MCP server** and paste the JSON below. (The cohort boilerplate already includes it in `.cursor/mcp.json`.)
2. Click **Connect** (or **Needs authentication**) next to `builders-zone`, sign in to builders.zone and click **Allow**.
3. In the chat, say "start builders.zone".

~/.cursor/mcp.json:

```json
{
  "mcpServers": {
    "builders-zone": {
      "url": "https://builders.zone/api/mcp"
    }
  }
}
```

### Codex (CLI and IDE extension)

1. Run both commands below.
2. Sign in to builders.zone in the browser window that opens and click **Allow**.
3. Say "start builders.zone".

Terminal:

```bash
codex mcp add builders-zone --url https://builders.zone/api/mcp
codex mcp login builders-zone
```

## Cloud agents (use a token)

Cloud agents run on a remote machine and can't open a sign-in window, so they use a personal token. Treat it like a password: it acts as you. Revoke it at https://builders.zone/app/settings/assistant if it leaks.

### Cursor cloud agents

1. Create a token on builders.zone at **Connect AI tool** in the builders.zone sidebar (https://builders.zone/app/settings/assistant).
2. In the Cursor dashboard open **Cloud Agents → Secrets** and add `BUILDERS_ZONE_TOKEN` with the token as its value.
3. In your repo, set `.cursor/mcp.json` to the JSON below and push. It names the secret; the token itself never goes in the repo.

.cursor/mcp.json:

```json
{
  "mcpServers": {
    "builders-zone": {
      "url": "https://builders.zone/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BUILDERS_ZONE_TOKEN}"
      }
    }
  }
}
```

### Claude Code on the web

1. Create a token on builders.zone at **Connect AI tool** in the builders.zone sidebar (https://builders.zone/app/settings/assistant).
2. In your Claude Code environment settings add the environment variable `BUILDERS_ZONE_TOKEN` with the token as its value.
3. In your repo, set `.mcp.json` to the JSON below and push. It names the variable; the token itself never goes in the repo.

.mcp.json:

```json
{
  "mcpServers": {
    "builders-zone": {
      "type": "http",
      "url": "https://builders.zone/api/mcp",
      "headers": {
        "Authorization": "Bearer ${BUILDERS_ZONE_TOKEN}"
      }
    }
  }
}
```

## Then

Say "start builders.zone" (or run the `start` prompt). Your tool walks you through: install your tools → get the boilerplate running locally → check your idea → build the first version locally.

## Troubleshooting

| Problem | Fix |
| --- | --- |
| "Authentication URL unavailable for this cloud MCP server" (Cursor) | Cloud agents can't open a sign-in window. Use the **Cursor cloud agents** steps: a token stored as a secret. |
| The Connect button does nothing (Cursor) | Click the **Needs authentication** text instead, or copy the sign-in link from **Output → MCP: builders-zone**. |
| "Resources are for cohort members" or a 403 | Sign in with the builders.zone account that has your cohort seat. |
| "Complete onboarding first" | Finish onboarding on builders.zone, then connect again. |
| Tools stopped working after a while | Disconnect and connect again. With a token: check it is not revoked. |