Commencer

Docs for agents

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.

On this page

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.

    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:

    {
  "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.

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.

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

#