Hosted MCP connector

Customize → Connectors → + → Add custom connector → paste https://mcp.percher.app/mcp → approve the Percher login. On Team/Enterprise, an owner first adds the connector under Organization settings; members then select Connect.

Add this entry to .cursor/mcp.json in your project, or ~/.cursor/mcp.json globally, then complete the OAuth login:

{
  "mcpServers": {
    "percher": {
      "url": "https://mcp.percher.app/mcp"
    }
  }
}

Add this entry to .agents/mcp_config.jsonin your project, or ~/.gemini/config/mcp_config.jsonglobally. Use Authenticate under Customizations to complete OAuth:

{
  "mcpServers": {
    "percher": {
      "serverUrl": "https://mcp.percher.app/mcp"
    }
  }
}

Add the URL as a remote MCP server and complete OAuth.

Codex speaks streamable HTTP and OAuth directly — register the URL, then sign in:

codex mcp add percher --url https://mcp.percher.app/mcp
codex mcp login percher

ChatGPT web takes the same URL:

• Web: enable Developer mode under Settings → Security and login, then open ChatGPT Plugins and add the URL there. Availability can depend on your account or workspace policy.

If your client can't talk to a remote server at all, bridge it with mcp-remote, which handles the OAuth dance and presents a local stdio server the client can talk to:

npx -y mcp-remote https://mcp.percher.app/mcp

• percher_publish — publish an app from source the assistant passes inline: the files it generated in your session (include a percher.toml). Percher packs them server-side, creates the app, and deploys. This is the hosted “I just said publish” path for an assistant with no local file access. Inline source is capped at ~25 MB; for a larger app, connect a repo.
• percher_upload — chunked, hash-verified upload + publish, ONLY for apps that can't fit in one percher_publish call (over ~64 KB of content, or heavy binary assets — every chunk call costs a model turn plus a possible approval, so smaller apps are much faster in one call). The assistant declares a manifest (per file: path, size, sha256 of the bytes on disk) that can inline small files directly, streams 32 KB verified chunks for the big ones (utf8 for text, base64 for binary), then commits — the server assembles, re-verifies every file, and publishes through the same path as percher_publish. A corrupted chunk is re-sent alone; nothing broken can deploy.
• percher_deploy — deploy the latest commit of a repo you've connected via the GitHub App. Percher clones it server-side. percher_redeploy re-runs the current version.
• percher_publish_from_git — publish a public repo by URL: Percher clones it server-side (one-shot, no webhook), reads its percher.toml, creates the app, and deploys. For a public repo you didn't build inline; private repos use the GitHub App + percher_deploy.
• List apps, app status and open an app
• Env set / list
• Custom domains
• Deploys: list, inspect and wait for a deploy
• Version history and diffs
• Visitor analytics (app owner on Starter, Maker or Max)
• Collaborator and ownership-transfer lists (read-only)
• Public inspect links
• Backups and data status
• Resume (unsuspend) an app, or put one to sleep

Manage or revoke connected clients in the Percher dashboard under Account → Connected apps.

Two differences from the local set matter: the hosted connector can't read files on your local disk, and it has no percher_doctor or percher_logs. If recovery asks for run_doctor, use percher_deploys_inspect with the known app and deploy ID to inspect build diagnostics. Ask the user when the target is ambiguous. For a project on your machine, deep diagnosis, or crash analysis, use the local package (see below).

percher_publish takes the files the assistant generated as an array of { path, content } (UTF-8) plus an optional name. Include a percher.toml that sets [app].name and runtime — or omit it and pass name, and Percher auto-detects the runtime from the files:

{
  "files": [
    { "path": "percher.toml", "content": "[app]\nname = \"my-site\"\nruntime = \"static\"\n" },
    { "path": "index.html", "content": "<!doctype html>\n<h1>Hello from Percher</h1>" }
  ]
}

Binary assets (images, fonts) can't travel as UTF-8 text — add "encoding": "base64" to that file and pass the base64-encoded bytes as content.

Integrity check (recommended for sandbox-generated files): each file also accepts an optional sha256 — the hex digest of the file's raw bytes (for base64 entries, the decoded bytes: hash the file on disk, not the base64 string). Inline content travels as assistant-generated text, so a long file can get corrupted in transcription without anyone noticing; with the hash declared, Percher verifies what it received and rejects the publish with a fix_problems recovery naming each mismatched file, so the assistant re-emits just those instead of deploying something silently broken.

The call defaults to async: it returns status: "queued" with a wait_deploy recovery, so resume with percher_wait_for_deploy to follow the build to its live URL (no long silent block while it builds).

The hosted connector can publish source the assistant hands it inline (percher_publish) or a connected repo (percher_deploy). What it can't do is read files on your local disk — a project folder the assistant can't see, a large app, or anything you'd publish from a terminal. For that, use the local MCP server npx -y @percher/mcp (or the CLI bunx percher publish), which reads your project directory.

• Local package (@percher/mcp / bunx percher publish) — publish from files on your machine, full tool set, runs on your machine.
• Hosted connector (mcp.percher.app/mcp) — publish an app the assistant built (inline) or a connected repo, operate existing apps, zero install.

For the local setup, see the MCP tools and Deploy instruction for AI agents sections.

The hosted connector uses OAuth 2.1 with a per-user login. Tokens are scope-limited and revocable in real time from the dashboard — revoking a client disconnects it immediately. Publishing is bounded by your plan's app and deploy limits, the same as the CLI.

Because any client can self-register (open Dynamic Client Registration), the consent screen shows the exact redirect origin the approval is sent to, plus an "unverified client" label. Check that origin before you approve.