Skip to main content

Deploy tokens

info

Deploy tokens are Pro+ only.

For CI or any machine where you cannot run micropage login, give the server a project deploy token instead of a session. The server then works on that one project only, with a reduced tool set.

Setup​

  1. Create a token in the web app under Settings → Deploy tokens (see Settings). It is shown once; store it as a secret.
  2. Find the project's uuid: it is shown in the app, in .micropage/project.json as projectUuid, and in list_projects output.
  3. Set both variables in the server's environment:
claude mcp add micropage \
  -e MICROPAGE_DEPLOY_TOKEN="$MICROPAGE_DEPLOY_TOKEN" \
  -e MICROPAGE_DEPLOY_PROJECT="$MICROPAGE_PROJECT_UUID" \
  -- npx -y @micropage-sh/mcp

or in a JSON client config:

{
  "mcpServers": {
    "micropage": {
      "command": "npx",
      "args": ["-y", "@micropage-sh/mcp"],
      "env": {
        "MICROPAGE_DEPLOY_TOKEN": "<token>",
        "MICROPAGE_DEPLOY_PROJECT": "<project uuid>"
      }
    }
  }
}

Set both or neither. With only one set, or with a project value that is not a uuid, the server exits at startup with an error naming the missing variable. When both are set, the server ignores any CLI session on the machine.

The server exchanges the token for a short-lived session and renews it as needed. The plan check is skipped, because only Pro+ accounts can create deploy tokens. whoami reports auth_mode: "deploy_token" and the pinned project.

What the server can do in this mode​

ToolAvailable
whoami, get_project, get_page_source, list_builds, list_filesYes
save_page, upload_assetYes
publish_build, get_deploy_statusYes
get_markup_referenceYes (local, no network)
Everything else (list_projects, create_project, posts, forms, submissions, delete_project)No: refused with NOT_ALLOWED_IN_DEPLOY_TOKEN_MODE

Every call must name the pinned project in project. A call for any other project is refused before anything is sent.

That covers the CI loop: read the current source, write new markup, save it as a draft, publish, and follow the deploy.

What the pin does and does not do​

The project pin and the tool list are enforced by the MCP server, on your machine. On the platform side, the session a deploy token is exchanged for currently carries your account's full owner access. So:

  • The pin limits what an assistant driving the server can reach, including one manipulated by text it read (prompt injection).
  • It does not limit what someone who has the token itself can do. Store the token as a secret, give it an expiry, and revoke it in Settings → Deploy tokens when it is no longer needed.

Do not auto-approve publish_build in an unattended setup unless publishing on every run is the intent. See Safety.

  • CI/CD: publishing with the CLI and a deploy token, without an assistant.
  • Install: all environment variables.