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.

Settings → Connected apps → Custom apps → Add a custom app → paste https://mcp.percher.app/mcp → approve the Percher sign-in. Percher registers itself (Dynamic Client Registration), so there are no credentials to paste. Google offers custom apps to personal accounts, 18 or over, in the US for now; once connected, the app works in the Gemini mobile app too.

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
• Database records (schema, query, get, create, update, delete), when enabled for your account and only for apps you give the connection access to, as the identity you choose for each app
• Resume (unsuspend) an app, or put one to sleep

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

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).

• An app user: the app's own access rules apply as they do for that user. “You” marks your own record, and only when its email matches your verified Percher email and the app has verified it.
• A visitor: not signed in; the assistant sees what the app's rules show anyone.
• Full access: bypasses the app's own rules. If the app's rules let only its superuser reach its data (its own server signs in as superuser), this is the only choice that reaches it.

• Code in the app's web page never runs: client-side validation, defaults, derived values and confirmation steps.
• The app's own server code, if it has one in front of PocketBase, is skipped: the tools talk to PocketBase directly. Under full access they reach its data without the server's own checks.
• Percher-managed PocketBase runs no custom pb_hooks. What applies is the collection rules, built-in field validation, autodate, cascade, hidden fields and email visibility.
• No sign-in happens. The app's auth rule is checked before every request; MFA and login alerts are not. If the chosen user's password changes between that check and the request, that one request runs as a visitor.
• Logic that must also apply to the assistant's changes belongs in the collection's API rules, for example @request.body.owner = @request.auth.id as a create rule. Percher never changes your app's rules, schema or code.

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.