# Docs for agents

> For a coding agent such as Claude Code, Cursor or Codex - connect to Playcode, sign the user in, call operations, and know when to ask the user.
> Source: https://playcode.io/docs/developers/agents - last reviewed 2026-10-10.

You are reading this because a user asked you to connect Playcode. Follow the five steps in order. Act only within what the user allowed, and stop to ask them at every point that step 5 names.

## 1. Know what Playcode is

Playcode is an AI platform for building and running websites and apps. The user's work lives in workspaces; each project is a static site or a Cloud app with its own development and production computers.

Every action goes through one API. The CLI, both MCP servers and the SDK call the same operations, and a refusal names the permission that was missing.

## 2. Install the CLI or add an MCP server

1. If you can run shell commands, install the CLI. It needs Node.js 22 or newer.

   ```bash
   npm i -g @playcode/cli
   playcode --version
   ```

2. If your client runs local MCP servers, install the CLI, then register `playcode mcp` as a command. It serves the tools over the CLI's sign-in:

   ```json
   {
     "mcpServers": {
       "playcode": {
         "command": "playcode",
         "args": ["mcp"]
       }
     }
   }
   ```

3. If your client connects to MCP servers only by address, add `https://playcode.io/api/mcp`. Your client signs the user in through Playcode. This server does not offer the permission to change files, run commands or publish.

## 3. Sign the user in

With the CLI, which `playcode mcp` also uses:

1. Run `playcode login --json`. The default permission is `projects:vm`: projects, files, commands and publishing. To ask for more, list every permission you need, like `--permissions projects:vm,domains:write` to manage domains too, or add `chats:write` to give tasks to Playcode's agent.
2. Read the first JSON object, `"step": "code"`. It holds `verification_uri`, `verification_uri_complete` and `user_code`. The command waits until the user finishes; if your shell shows output only when a command ends, run it in the background.
3. Give the user the address and the code. They open the page, type the code, choose **Continue**, then **Yes, sign in**, pick a workspace and choose **Allow**. The code expires after 10 minutes.
4. When the command prints `"step": "signed-in"`, check the sign-in with `playcode whoami`.

Instead of the browser, the user can create an access token on the **Developers** page of the workspace settings, then set `PLAYCODE_TOKEN` in your environment or run `playcode login --paste` themselves. Never ask the user to paste a token into the chat. See [Access tokens and permissions](/docs/developers/tokens-and-permissions).

With the hosted MCP server, your client opens Playcode's sign-in page. The user checks what you may do, picks a workspace and chooses **Allow**.

Every sign-in acts in one workspace, with the permissions the user allowed.

## 4. Call operations

Find the operation, read its arguments, then call it:

| Through | Find | Read the arguments | Call |
|---|---|---|---|
| MCP | `search_operations` | `describe_operation` | `read_operation`, `write_operation` |
| CLI | `playcode <family>` | `playcode <family> <operation> --help` | `playcode <family> <operation> --<argument> <value>` |

The CLI also has commands of its own. Add `--json` to any command for output you can parse.

| Command | What it does |
|---|---|
| `playcode projects` | The projects the user owns, with the uid and the name each one answers to |
| `playcode vm ls <project> [path]` | Lists a project's files |
| `playcode vm cat <project> <path>` | Prints one file |
| `playcode vm exec <project> -- <shell line>` | Runs a command on a Cloud app's computer and exits with its exit code |
| `playcode vm cp <local> <project>:<path>` | Uploads a file or a folder; the reverse order downloads |
| `playcode publish <project> --wait` | Publishes a Cloud app and waits until the publish ends |

What the families cover:

| Family | What you can do | Permission a token needs |
|---|---|---|
| `projects` | Read projects and their files; write files, run commands and publish | `projects:read` to read; `projects:vm` to change |
| `domains` | Search and buy names, connect domains, edit DNS records | `domains:read` to read; `domains:write` to change |
| `chats` | Give Playcode's agent a task in a project's chat. Reach it through MCP: the CLI does not list this family yet | `chats:write` |
| `events` | Read the workspace's activity | None |
| `consent` | Create and decline proposals | None |
| `api` | Search and describe operations | None |

No token reaches access tokens, webhooks or an app's own settings, such as its email, secrets and AI. Those stay with the signed-in user, in the app: its settings, or the agent in a chat.

A refused call carries a code: `missing_scope` names the permission it needed in `metadata.needs`. Ask the user to sign in again with that permission. Every code: [Errors](/docs/developers/api#errors).

## 5. Stop and ask the user

Ask, and wait for the user's explicit yes in their own message, before:

1. **Spending money.** Buying or transferring a domain (`domainCreate`, `domainTransfer`, effect `MONEY`). A first publish of a project, which creates its production computer; that computer uses credits while it runs. A task for Playcode's agent (`chatUserMessageCreate` with `respond: true`), which uses the workspace's credits.
2. **Any operation that needs consent.** Call `proposalCreate` with the operation and its exact arguments, and show the user the `terms` word for word. Only after their yes, call the operation with `proposalId`. A money proposal lasts 15 minutes, any other 1 hour. If the user says no, call `proposalDecline`. Never confirm a proposal the user did not approve.
3. **Deleting.** Files (`projectFileDelete`, or `rm` through `playcode vm exec`), a DNS zone (`dnsZoneDelete`), a domain's connection to a project (`domainDisconnect`), and anything else you cannot undo.
4. **Publishing.** Publish only when the user asks: when the publish ends, visitors see the new version.
5. **Changing a plan or buying credits.** You cannot do either. Tell the user to open **Settings** and choose **Billing & plans**.
6. **Steps only the user can take.** A setting at a DNS provider outside Playcode, verifying an email address, anything in their Stripe account, and connecting Search Console or Notion.

Never print or store a token, a secret key or a sign-in code in the chat, in code or in a URL.

## Read more

- [The Playcode CLI](/docs/developers/cli): every command, flag and exit code.
- [Connect Claude Code, Cursor or another MCP client](/docs/developers/mcp): the two MCP servers.
- [The API](/docs/developers/api): the endpoint, errors, consent and idempotency.
- Every page of these docs answers as Markdown at its address plus `.md`. The list of pages: https://playcode.io/docs/llms.txt