# Cloudflare Activation Guide

Canonical page: https://www.kuudo.com/docs/cloud/cloudflare-activation-guide/


This guide explains how to prepare Cloudflare so the in-app **environment wizard** (Configuration → Credentials with inline Validate → Review & create) can create infrastructure successfully.

**Core idea:** prepare Cloudflare first (in the dashboard, optionally verified with `curl` or `wrangler`), then paste your API token into the product. The app derives account details from that token during validation.

---

## Quick path

1. Sign in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select the correct account ([§ Sign in and select the account](#sign-in-and-select-the-account)).
2. (Optional) Copy the **Account ID** from account home for troubleshooting ([§ Account ID](#copy-the-account-id-optional)).
3. Create an **API token** with the required Cloudflare permissions and save the **token value** ([§ API token](#create-an-api-token)).
4. Confirm the token can read your account ([§ Verify the token](#verify-the-api-token)).
5. Open the wizard: **Configuration** → **Credentials** (click **Validate**) → **Review & create** ([§ Complete the wizard](#complete-the-wizard-in-the-app)).
6. If something fails, use [§ Common issues](#common-issues).

---

## Prerequisites

- Access to the target Cloudflare account.
- Permission to create API tokens for that account (Super Administrator, or a role that includes "Account API Tokens: Edit").
- Optional: [`wrangler`](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed locally, or any tool that can call `https://api.cloudflare.com`.

The dashboard is recommended for token creation because tokens can only be created from the UI. CLI tools are useful for verification.

---

## Field reference

The wizard matches Cloudflare outputs like this:

| What you do in Cloudflare              | Output to copy                  | Wizard field                     |
| -------------------------------------- | ------------------------------- | -------------------------------- |
| My Profile → API Tokens → Create Token | **Token value** (shown once)    | **Cloudflare API Token**         |
| (your label only)                      | Any name                        | **Environment Name**             |
| Account home → right sidebar           | Account ID (optional reference) | _(auto-derived during validate)_ |

**Account ID vs Token:** the Account ID is a 32-character hex string (for example `a1b2c3d4e5f67890abcdef1234567890`). The API token is a longer secret string starting with letters and numbers — **not** a Global API Key. Never use the Global API Key with this wizard; it grants too much access and is not scoped to the resources we provision.

**Workers subdomain** (`<your-name>.workers.dev`) is discovered automatically during provisioning/deployment flows; you do not need to enter it.

**Region:** Cloudflare runs on a global anycast network, so there is no region field. Containers and Workers are placed automatically near end-users.

---

## Prepare Cloudflare with the dashboard

Run the steps below as **a Cloudflare account admin**.

### Sign in and select the account

1. Open <https://dash.cloudflare.com>.
2. If you belong to multiple accounts, pick the correct one from the account switcher (top-left).

### Copy the Account ID (optional)

1. Click the account name to land on the **account home** page.
2. In the right sidebar, find **Account ID** and click the copy icon.
3. Save it as a troubleshooting reference (the wizard does not ask for Account ID directly).

You can also retrieve it with `wrangler`:

```bash
wrangler whoami
```

The output lists the accounts your current `wrangler` login can see along with their IDs.

### Create an API token

1. Top-right avatar → **My Profile** → **API Tokens** → **Create Token**.
2. Choose **Create Custom Token** (the templates do not include Containers).
3. Name it something memorable, e.g. `mcp-deployment-token`.
4. Add the following **permissions** (all Account-scoped):

   | Resource                        | Permission |
   | ------------------------------- | ---------- |
   | Account → Account Settings      | Read       |
   | Account → Workers Scripts       | Edit       |
   | Account → Workers Scripts       | Read       |
   | Account → Workers R2 Storage    | Edit       |
   | Account → Containers            | Edit       |

5. Under **Account Resources**, select **Include → Specific account → \<your account\>**.
6. Leave **Client IP Address Filtering** blank unless you have a fixed egress IP.
7. **TTL:** leave open-ended unless your security policy requires expiry. If you set a TTL, you will need to rotate the token in the wizard before it expires.
8. Click **Continue to summary** → **Create Token**.
9. Copy the **token value immediately**. Cloudflare only shows it once.

> **Why these permissions?**
> Account Settings: Read enables account discovery during token validation. Workers Scripts permissions support worker deployment and reads. Containers is required for container-based MCP runtime. Workers R2 Storage is needed when attaching R2-backed storage.

If you need to rotate later: return to **My Profile → API Tokens**, click the existing token → **Roll**, then update **API Token** in the wizard.

### Verify the API token

This separates Cloudflare misconfiguration from product issues. Replace `<API_TOKEN>` and `<ACCOUNT_ID>` with your values.

```bash
# 1. Token can read accounts (matches the wizard's validation call)
curl -sS https://api.cloudflare.com/client/v4/accounts \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json"

# 2. Token can read the specific account you intend to deploy to
curl -sS https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID> \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json"

# 3. Optional: token self-verification endpoint
# Note: some account-scoped tokens may not return useful results here.
curl -sS https://api.cloudflare.com/client/v4/user/tokens/verify \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json"
```

`/accounts` and `/accounts/<ACCOUNT_ID>` should return JSON with `"success": true`. If `accounts` returns an empty `result` array, the token is missing **Account Settings: Read** or is scoped to the wrong account.

You can also verify with `wrangler` by exporting the token:

```bash
export CLOUDFLARE_API_TOKEN=<API_TOKEN>
export CLOUDFLARE_ACCOUNT_ID=<ACCOUNT_ID>
wrangler whoami
```

---

## Complete the wizard in the app

Use the [Field reference](#field-reference) for definitions.

### Configuration

- **Environment Name** — label in your app (for example `cloudflare`).

### Credentials

- **API Token** — token **value** from [§ API token](#create-an-api-token).

### Validation

Run validation in the UI (Credentials step → **Validate**). It should succeed when the token is valid and can list at least one account. The app derives account details from that result.

### Review & create

After validation succeeds, finish creating the environment.

---

## Common issues

| Symptom or error                                                                                 | Likely cause                                                   | What to do                                                                                                                                             |
| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Invalid API token` / HTTP 401 from `tokens/verify`                                              | Wrong token, expired token, or Global API Key pasted instead   | Create a new API token (not a Global API Key); copy the value; update the wizard ([§ API token](#create-an-api-token)).                                |
| `No Cloudflare accounts found. Your API token may not have 'Account Settings: Read' permission.` | Token missing **Account Settings: Read**                       | Edit the token and add **Account → Account Settings: Read**, then re-run validation.                                                                   |
| Validation OK but provisioning fails with `Authentication error` on Workers/Containers/R2        | Token missing **Edit** on one of the required resources        | Edit the token and add **Workers Scripts: Edit**, **Containers: Edit**, **Workers R2 Storage: Edit** ([§ API token](#create-an-api-token)). |
| Validation says no account found                                                                 | Token cannot list accounts or is scoped to a different account | Confirm **Account Settings: Read** and that token **Account Resources** include the target account.                                                    |
| `workers.dev subdomain not configured` during deployment                                         | The account has never enabled a Workers subdomain              | Visit **Workers & Pages → Overview** in the dashboard once to provision the subdomain, then retry provisioning/deployment.                             |
| Token expires unexpectedly                                                                       | TTL was set when the token was created                         | **My Profile → API Tokens → Roll** the token, paste the new value into the wizard, and consider removing the TTL.                                      |
| `Containers` permission not visible when creating the token                                      | Account is not enrolled in Cloudflare Containers               | Enable Cloudflare Containers from **Workers & Pages → Containers**, then create the token.                                                             |
| Pasted the **Global API Key** instead of an API token                                            | Wrong credential type                                          | Create an API token via **My Profile → API Tokens → Create Token**; never use the Global API Key here.                                                 |

## Official references

- [Cloudflare API token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)
- [Wrangler commands](https://developers.cloudflare.com/workers/wrangler/commands/)
- [Wrangler configuration](https://developers.cloudflare.com/workers/wrangler/configuration/)
- [Cloudflare API reference](https://developers.cloudflare.com/api/)

---

## Appendix: Copy-paste verification script

The block below repeats [§ Verify the token](#verify-the-api-token) in one place for convenience. Replace placeholders before running.

```bash
export CLOUDFLARE_API_TOKEN=<API_TOKEN>
export CLOUDFLARE_ACCOUNT_ID=<ACCOUNT_ID>

# Token can list accounts (matches wizard validation)
curl -sS https://api.cloudflare.com/client/v4/accounts \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json"

# Token can read the specific account
curl -sS "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json"

# Optional: token self-verification endpoint
curl -sS https://api.cloudflare.com/client/v4/user/tokens/verify \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json"

# Optional: confirm with wrangler
wrangler whoami
```

After this succeeds, fill the wizard using the [Field reference](#field-reference) and complete [§ Complete the wizard](#complete-the-wizard-in-the-app).