The server publishes local folders, single HTML files, or already-running apps to public Cloudflare URLs, with optional private key-gating, Cloudflare Access identity sign-in, and account-level cataloging.
deploy: Publish a folder or .html file to a Cloudflare URL via quick tunnel (no account) or Workers (fixed URL when signed in); supports private key-gated links, public deploys, Cloudflare Access email allowlists, expiry, and redeploys.
expose: Publish an app already listening on a port, locally or on a remote machine over SSH, with HTTP/WebSocket proxying, private-by-default key gate, and optional expiry.
list: List all deploys with backend, status, and URL.
catalog: Show every deploy in the Cloudflare account grouped by project, filter by project, and optionally publish a browsable catalog page (with Access sign-in by default).
project: Assign a deploy to a project (or clear it) without redeploying.
credentials: Store the app's own username/password/note alongside a deploy, shown only on a gated catalog page.
status: Show one deploy's state and an HTTP check of its public URL.
rotate: Issue a new private key for a live deploy, invalidating the old link/sessions; can also turn a public deploy private.
stop: Stop a tunnel deploy's local server and tunnel (keeps the record).
remove: Stop and delete a deploy record/logs; on Workers also deletes the Cloudflare worker.
logs: Fetch recent deploy logs (host, cloudflared, wrangler).
doctor: Run diagnostics for cloudflared, Cloudflare sign-in, default backend, and active deploys.
Enables publishing local folders, single HTML files, and apps listening on a port to public Cloudflare URLs, using Cloudflare quick tunnels with optional private key-gated links and account-based deployments.
Allows deploying static site assets to Cloudflare Workers with fixed worker.dev URLs, including listing, status, rotation, removal, and log management for deployments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cloudfact deploy ./report.html to a public URL"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Publish a folder, a single HTML file, or an app that is already listening on a port (locally or on a machine reachable over SSH) to a public Cloudflare URL with one command. Ships as a CLI, an MCP server (works with Claude Code, Codex, Cursor, Claude Desktop, Windsurf…) and a /cloudfact skill.
cloudfact deploy ./report.html # → https://xxxx.trycloudflare.com/#key=… (private link, no account needed)
cloudfact login --device && cloudfact deploy ./site # → https://site.<your-sub>.workers.dev/#key=… (fixed URL, your account)
cloudfact deploy ./site --public # open to anyone with the URL
cloudfact expose 3000 --ssh ubuntu@my-vm # app on another machine, over SSH (private link)Claude Code — two commands, no clone, no npm install (skill /cloudfact + MCP server):
claude plugin marketplace add gabrielchaves6/cloudfact
claude plugin install cloudfact@cloudfactEverything at once (CLI on PATH, Claude Code plugin, Codex skill + MCP). Requires Node 20+ and git:
curl -fsSL https://raw.githubusercontent.com/gabrielchaves6/cloudfact/main/install.sh | bashCodex — register the server and the skill from cloudfact itself (works on Windows too, unlike the shell installer):
cloudfact setup --codex # or: npx/node <path>/dist/bin.js setup --codexIt writes [mcp_servers.cloudfact] into Codex's config (through codex mcp add when the CLI is
around, by editing config.toml otherwise, leaving your other servers alone) and copies the skill into
$CODEX_HOME/skills/cloudfact, minus the frontmatter keys Codex refuses. Restart Codex afterwards. Run
it again after an update: it replaces its own entry instead of piling up copies.
Any other MCP client (Cursor, Windsurf, Claude Desktop…): clone and point at the bundled, dependency-free server:
{ "mcpServers": { "cloudfact": { "command": "node", "args": ["/path/to/cloudfact/dist/server.js"] } } }It works without any login through the quick tunnel. cloudflared is downloaded automatically on the first deploy (Linux/macOS, x64/arm64) into ~/.cloudfact/bin; if you already have it on PATH, yours is used.
Related MCP server: EdgeOne Pages MCP
expose)Anything that already listens on a port can be published the same way, with HTTP and WebSocket proxied and the same optional --private gate:
cloudfact expose 3000 # app running on this machine (private link by default)
cloudfact expose 3000 --ssh ubuntu@10.0.0.5 # app running on another machine, reached over SSH
cloudfact expose 8080 --ssh myvm --public # `myvm` = Host alias from ~/.ssh/config; no key gateApps are private by default (key-gated link, see below), like every other deploy; pass --public to opt out. With --ssh, cloudfact opens an ssh -N -L port-forward to the remote app and publishes through the local tunnel. Nothing is installed on the remote machine; it only needs key-based SSH access (--ssh-port, --identity, --strict-host-key available). The forward and the tunnel are supervised and reconnect if they drop. MCP tool: expose.
Two options. The first works even when you only reach the machine through an agent (Claude Code, Codex…): the agent runs the command, relays the link and the code, and you approve in a browser on any device.
cloudfact login --device # browser OAuth (wrangler login --device); no token ever goes through the chat
cloudfact login --token <tok> # or an API token: https://dash.cloudflare.com/profile/api-tokens ("Edit Cloudflare Workers" template)Tokens are stored in ~/.cloudfact/config.json (0600); OAuth credentials live where wrangler keeps them (~/.config/.wrangler). CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID also work. cloudfact logout forgets.
After signing in the default backend becomes workers; --backend tunnel remains available.
backend | account? | URL | how |
| no |
| local static server + |
| yes |
| Cloudflare Workers with static assets, the successor of Pages (Cloudflare no longer creates new Pages projects). |
Every deploy is private unless you pass --public: cloudfact generates a 256-bit key; the returned URL carries it in #key=…, which browsers never send to servers. Without the cookie every route returns only a gate page, which exchanges the fragment for an HttpOnly, Secure cookie via POST /api/session. That endpoint is rate-limited per visitor IP (10 attempts/minute) and failures are logged to the deploy's host.log.
cloudfact deploy ./report --private --expires 24h # link stops working after 24h
cloudfact rotate report # new key now; old link and all sessions die
cloudfact rotate report --expires 2h # new key with a lifetimerotate works on a live deploy without restarting it (on the tunnel backend it also turns a public deploy private). On the workers backend the gate is a tiny generated Worker running in front of the files (run_worker_first), the key is a Worker secret, and rate limiting uses Cloudflare's rate-limit binding.
A private link is still a bearer link. For real identity, put Cloudflare Access in front of a workers deploy: visitors get a Cloudflare sign-in page, enter a one-time code sent to their email, and only the emails you list get in. Works on *.workers.dev, so you do not need to own a domain.
cloudfact login --token <api-token> # once; the browser login has no Access scopes
cloudfact deploy ./site --access you@example.com,ana@x.com # → https://site.<sub>.workers.dev, sign-in requiredThe API token needs the "Edit Cloudflare Workers" template plus Access: Apps and Policies — Edit and Access: Organizations, Identity Providers, and Groups — Edit. cloudfact creates the Zero Trust team (<team>.cloudflareaccess.com) and the one-time PIN provider on first use, then one self-hosted Access application per deploy, updated in place on redeploy and deleted by remove. The generated Worker verifies the Access JWT on every request (Cf-Access-Jwt-Assertion, RS256 against the team's public keys, audience pinned to this app) and refuses anything else, so a misconfigured policy fails closed instead of open.
Verified end-to-end on a real Cloudflare account (2026-09-15): the team, the one-time PIN provider and the application were created through the API alone, no Zero Trust checkout or payment method was required, the *.workers.dev URL redirects to the <team>.cloudflareaccess.com sign-in page, and after the email code the site is served.
Plan limit: cloudfact uses the Zero Trust Free plan, which allows 50 seats per Cloudflare account. A seat is one person who signs in, counted across every --access deploy in the account, so keep the sum of distinct emails you allow under 50 (Cloudflare blocks the 51st user until you upgrade). Seats of people who stop signing in can be released automatically from Zero Trust → Settings → "Remove inactive users from seats".
Local server safety: serves only what is inside the published folder, never dotfiles, no path traversal. A single .html is served alone (relative assets are not included; publish the folder in that case).
The Cloudflare account is the source of truth. cloudfact tags each Worker it creates (cloudfact, plus
the project, the visibility and the kind), so one listing rebuilds the whole picture from any machine,
even after a reinstall.
cloudfact deploy ./painel --project migracao # file it under a project
cloudfact catalog # everything in the account, grouped by project
cloudfact catalog --project migracao --json # one project, machine readable
cloudfact project painel financeiro # move it, no redeploy
cloudfact catalog --publish # publish the page; later deploys refresh itEach entry says what the deploy is and who can open it: Public, Private link (key-gated),
Sign-in (Cloudflare Access) or App login (the app behind it asks for its own username and
password, which cloudfact cannot supply: record it with cloudfact creds and the card keeps it), and
Static (files served by Cloudflare) or Server app (an app
with its own server behind the proxy). Quick tunnels have no account-side resource, so they are found on the
machine itself: cloudfact asks the running cloudflared processes for their public hostname, which also
surfaces pages still serving from here that this machine has no record of (flagged no local record:
published by an older cloudfact, from another folder, or by another tool), next to the ones it does
know (local tunnel). --publish deploys the
catalog as a page with a card per deploy, search, a list view and a filter per project. Each card shows a
real thumbnail, captured when the catalog is published from whatever this machine can already read: the
published folder, the app's own port, or the URL with its private key. Thumbnails render with scripts off in a sandboxed frame, and a deploy this
machine cannot see falls back to a monogram. The page never points a frame at a live site: doing so lets
that site challenge the visitor for credentials.
Because the page is behind sign-in, it can also be the one place that opens everything: each card links
to the deploy with its private key already in the link, so a page you are allowed to see opens in one
click. cloudfact creds <name> --user u --password p --note n records the login of the app itself (a
terminal, a dashboard) next to the deploy; it stays on this machine and is shown, behind a click, only on
a catalog page that is itself gated. A catalog published with --public carries neither keys nor logins. The page is an index of everything you host, so it asks for
Cloudflare Access sign-in by default, for the email that owns the account; pass --access to choose who
else gets in, or --public to opt out. MCP tools: catalog, project.
The pages cloudfact generates carry the CloudFacts identity: the mark, CloudFacts Sans and an off-white
#F4F4F1 on a dark surface. The catalog page is published with the font files beside it and the private
gate carries the mark inline, so neither fetches anything from the network when someone opens it. The
font ships in weights 400 and 500 only, which is why nothing asks for a bolder one: the browser would
fake it. Assets and their licence live in brand/. Your own pages are never restyled;
cloudfact only dresses the pages it makes.
Stdio server. Tools: deploy, expose, list, status, rotate, stop, remove, logs, doctor — see docs/tools.md (generated from the code). Prompt: cloudfact. Sign-in is deliberately outside the MCP: run cloudfact login in a terminal so the token never enters the agent context.
Skill /cloudfact <path> [--private] [--name x] [--tunnel|--workers] lives in skills/cloudfact/SKILL.md; the Claude Code plugin ships it, and install.sh links it into ~/.codex/skills.
cloudfact deploy [path] [--name n] [--public] [--expires 24h] [--backend auto|tunnel|workers] [--restart] [--json]
cloudfact expose <port> [--name n] [--public] [--expires 24h] [--ssh user@host] [--ssh-port 22] [--identity key] [--strict-host-key] [--restart] [--json]
cloudfact rotate <name> [--expires 24h]
cloudfact list | status <name> | stop <name>|--all | rm <name> | logs <name> [-n 40]
cloudfact doctor | setup | login --device | login --token T [--account-id ID] | logout
cloudfact config get | set <key> <value>
cloudfact mcp # MCP server over stdioState: ~/.cloudfact/deploys/<name>/ (state.json, host.log, tunnel.log, wrangler.log). Different directory: CLOUDFACT_HOME=/x.
TypeScript. Runtime dependencies (MCP SDK and zod) are bundled into dist/.
src/
bin.ts CLI entry → dist/bin.js
server.ts MCP entry (stdio) → dist/server.js
index.ts public API (library) → dist/index.js + .d.ts
cloudfact.ts use cases: deploy, stop, remove, status, doctor
config.ts types.ts logger.ts
mcp/
server.ts createServer(): registers tools and prompt
define-tool.ts typed defineTool() with annotations (readOnlyHint, destructiveHint)
tools/ tool definitions
backends/
tunnel/ static-server.ts · proxy.ts (expose: HTTP + WebSocket) · gate.ts (private mode) · host.ts (detached process → dist/host.js) · index.ts
workers/ wrangler deploy --assets
services/ state (atomic on disk) · cloudflared (lookup/download) · wrangler · auth (token / device)
tests/ vitest: static server, state, MCP in-memory, workers with a fake wrangler, CLI
scripts/ generate-docs (docs/tools.md from the tool definitions) · verify-versions
skills/cloudfact/ the /cloudfact skill
.claude-plugin/ plugin and marketplace manifests
server.json MCP registry manifestnpm run check # typecheck + lint + test + build + docs + version sync (what CI runs)
npm test # vitest
npm run build # tsup → dist/ (committed on purpose: the plugin works straight from git, no npm install)
npm run docs # regenerate docs/tools.md
npm run inspect # MCP Inspector against dist/server.jsCI fails if dist/ or docs/tools.md are stale, or if the version differs across package.json, server.json and the plugin manifests. Every push to main is released automatically (patch bump by the workflow; npm run bump for minor/major). See CONTRIBUTING.md and SECURITY.md.
Cloudflare Access on the tunnel backend (needs a domain of your own + named tunnel).
Other identity providers (Google, GitHub) for Access besides the one-time PIN.
cloudfact run: rsync a project to an SSH host, start it there, and expose it in one step.
--private on the workers backend (minimal worker checking the cookie).
Named tunnel (fixed URL on your own domain).
npm publish (npx cloudfact).
HTTP transport for remote MCP connectors (claude.ai web).
MIT
Every cloudfact in the user's Cloudflare account, grouped by project, as the account itself sees them (so deploys made from another machine show up too). Each entry says whether it is public, a private key link or behind Cloudflare Access sign-in, and whether it serves static files or an app with its own server. Quick tunnels have no account-side resource and appear only when this machine still has their record (inAccount=false). publish=true turns the catalog into a browsable page and returns its URL; that page asks for Cloudflare Access sign-in by default, for the email that owns the account.
| Name | Required | Description | Default |
|---|---|---|---|
| access | No | With publish: emails allowed to sign in to the catalog page (default: the account owner) | |
| project | No | Only deploys filed under this project | |
| publish | No | Publish the catalog as a page and return its URL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false, but the description discloses the key behavioral side effect: setting publish=true creates a browsable page and returns its URL, with Cloudflare Access sign-in by default. It also explains how quick tunnels are represented and the inAccount=false flag. This adds valuable context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph, but it is well-structured: main purpose first, then entry details, then quick tunnel caveat, then publish behavior. Every sentence contributes new information. It is slightly long but efficient and front-loaded with the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, the description must explain the return value. It describes what each catalog entry contains (public/private/access, static vs. server) and covers the publish URL behavior. It does not mention ordering, pagination, or error cases, but for a list-style tool these are minor gaps. Overall it is sufficiently complete for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds extra meaning for the publish parameter ('turns the catalog into a browsable page and returns its URL') and clarifies the access parameter default (owner email). These details go beyond the schema descriptions, enhancing parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: it lists every cloudfact in the account, grouped by project, from the account's perspective. It also distinguishes itself from potential siblings by noting it includes deploys from other machines and excludes quick tunnels without a local record. The verb 'catalog' is implicit but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (for an account-wide view) versus a local view, but it never explicitly names alternatives or says 'use list for local records'. The note about deploys from other machines hints at differentiation, but there is no direct 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record how to get into the app behind a deploy (its own username/password/note, not cloudfact's). Stored with the deploy on this machine and shown only on a catalog page that is itself behind Cloudflare Access sign-in. Pass creds=null to clear. Never put the user's secrets in your reply.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Deploy name | |
| note | No | Anything else needed to get in | |
| user | No | The app's username | |
| clear | No | Forget the stored login | |
| password | No | The app's password |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that credentials are stored with the deploy on the machine, visible only on a Cloudflare Access-protected catalog page, and that clearing is possible. It also warns against echoing secrets, which is safety-relevant. This adds meaningful behavioral context without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose first, storage/access context second, usage and security guidance third. Every sentence contributes, but the `creds=null` phrasing unnecessarily introduces ambiguity, preventing a top score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose, storage location, access restrictions, and a security instruction, which is strong for a write tool. However, the clearing mechanism is described via a parameter that does not exist in the schema, and there is no clarification of what the tool returns. This leaves an important operational gap for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents every parameter. The description does not meaningfully add to parameter semantics and actively introduces a non-existent `creds` parameter for clearing, while the schema defines a `clear` boolean. This is misleading and could cause an agent to attempt an invalid call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records app-specific login information for a deploy and explicitly distinguishes it from cloudfact's credentials. The verb 'Record' plus the resource ('how to get into the app behind a deploy') makes the purpose unambiguous and differentiates it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context about where credentials are stored and shown, and it includes a critical safety instruction: 'Never put the user's secrets in your reply.' It also excludes cloudfact credentials. However, it does not name an alternative tool or provide a full when-not-to-use set, and the clearing instruction 'Pass creds=null to clear' is ambiguous because no `creds` parameter exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish a folder (or a single .html file) from this machine to a public Cloudflare URL. "tunnel" backend (default when signed out): local static server + cloudflared quick tunnel, *.trycloudflare.com URL; the process runs in the background and outlives the session. "workers" backend (default when signed in): Cloudflare Workers with static assets, fixed URL https://..workers.dev; redeploying updates the same address. Idempotent on tunnel: if the same path is already live, returns the existing URL (reused=true). Deploys are PRIVATE by default on both backends (key-gated link; on workers a gate Worker runs in front of the files); pass public=true to publish openly. access=[emails] (workers backend, API-token login) puts Cloudflare Access in front instead: visitors sign in with a one-time email code and only listed emails get in. Returns JSON with url and, when private, privateUrl (already includes #key=...).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Deploy name (slug). Defaults to the folder/file name | |
| path | Yes | Absolute path of the folder or .html file to publish | |
| access | No | Emails allowed to sign in through Cloudflare Access (identity gate instead of the key link; workers backend) | |
| public | No | Publish without the key gate (default false: private) | |
| backend | No | auto = workers when signed in to Cloudflare, otherwise tunnel | |
| expires | No | Private key lifetime, e.g. "30m", "24h", "7d" (default: never expires) | |
| restart | No | Restart even if already live (yields a new URL on tunnel) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and idempotentHint=true, and the description elaborates on both: it explains the background process that outlives the session, the key-gated privacy default, the access control via Cloudflare Access, and the exact return JSON shape (url and privateUrl). It discloses far more than the annotations alone, which is essential for a mutating tool with security implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long (~150 words) but each sentence carries distinct value: it covers backends, idempotency, privacy, access control, and return format. It is front-loaded with the core purpose and then systematically explains behavior. While not terse, the density of information justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, two backends, and security nuances, the description covers all critical aspects: deployment behavior, idempotency, privacy, access control, expiration, and return JSON. It even notes the tunnel process runs in the background. There is no output schema, but the description explicitly states the JSON fields, making it complete for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 7 parameters have schema descriptions (100% coverage), but the description adds meaningful nuance: it clarifies the backend default based on sign-in status, the semantics of 'access' (only on workers, requires API-token login), and the effect of 'restart' (yields a new URL on tunnel). This goes beyond the schema's basic property descriptions, though it could be more explicit about edge cases like 'expires' on the workers backend.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('publish') and resource (a folder or .html file) and explains the two backends (tunnel vs workers) and their URL outcomes. It clearly distinguishes the tool's purpose from siblings like 'expose' by detailing the deployment mechanisms and idempotent behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use each backend (signed out vs signed in) and explains idempotent redeployment. It does not explicitly mention alternative tools or when to avoid using it, but the backend selection guidance effectively steers the agent toward the right invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diagnostics: cloudflared, Cloudflare sign-in, default backend and active deploys. Run it before deploy when something fails.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true is present, which already indicates a non-mutating operation, so the description need not re-state that. The description adds useful context by enumerating the diagnostic areas, which hints at the breadth of information returned. However, it does not disclose specifics like output format, time costs, or whether it requires network access (e.g., cloudflared checks). With annotations covering the read-only aspect, a 3 is fair: the description adds some value but not deep behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence followed by a usage directive. It is front-loaded with the diagnostic topics, which are the core value, and the usage guidance is appended. It avoids fluff and is appropriately sized for a simple no-parameter tool. The only minor issue is that 'Diagnostics' in the title is redundant with the description, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no parameters, no output schema, and a readOnlyHint annotation, the description is relatively complete: an agent knows when to run it (before deploy on failure) and what it checks. However, it lacks details about the output format or how to interpret results, which could be important for an agent deciding whether to proceed. For a status-like tool, mentioning what a successful or failing output looks like would enhance completeness, so a 3 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100% vacuously (no properties). The baseline for no parameters is 4. The description does not need to explain parameters, and it effectively communicates the tool's no-input nature. It also indirectly implies that no configuration is needed, which aligns with the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description lists specific diagnostic subjects ('cloudflared, Cloudflare sign-in, default backend and active deploys'), which is helpful, and the verb 'Run' implies execution. However, the tool name 'doctor' and title 'Diagnostics' are generic, and the description does not clearly distinguish it from siblings like 'status' or 'logs', which might also provide diagnostic information. It states what it does but leaves the scope fuzzy relative to alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a clear usage trigger: 'Run it before deploy when something fails.' This gives a specific when-to-use condition and mentions the deploy context, aligning with the sibling 'deploy'. However, it does not explicitly state when not to use it or how it differs from 'status' or 'logs', leaving the agent to infer the right alternative for other diagnostic needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish an app that is already listening on a port to a public *.trycloudflare.com URL (tunnel backend). Without ssh, the port is on this machine. With ssh (user@host), the app runs on another machine: cloudfact opens an SSH port-forward to it and publishes through here — nothing to install remotely (key-based SSH access required). HTTP and WebSocket traffic is proxied. Apps are PRIVATE by default (same #key gate as static deploys, with rate limiting and optional expiry); pass public=true to publish without the gate. Idempotent: the same port/host already live returns the existing URL (reused=true).
| Name | Required | Description | Default |
|---|---|---|---|
| ssh | No | SSH destination of the machine running the app, e.g. ubuntu@10.0.0.5 or a Host alias from ~/.ssh/config | |
| name | No | Deploy name (slug). Defaults to port-<port> or <host>-<port> | |
| port | Yes | Port the app listens on (locally, or on the SSH host) | |
| public | No | Publish without the key gate (default false: private) | |
| expires | No | Private key lifetime, e.g. "30m", "24h", "7d" (default: never expires) | |
| restart | No | Restart even if already live (yields a new URL) | |
| sshPort | No | SSH port (default 22) | |
| identity | No | Path to the SSH private key (default: ssh agent / ~/.ssh/config) | |
| strictHostKey | No | Require the SSH host key to be in known_hosts already (no first-connection trust) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotentHint annotation, the description discloses concrete behavior: idempotent reuse with reused=true, key-based SSH requirements, private-by-default key gate, rate limiting, optional expiry, HTTP/WebSocket proxying, and restart behavior. This is rich, non-obvious behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place. The core purpose is front-loaded, followed by SSH mode, security defaults, and idempotency. No filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters, remote SSH behavior, security gates, and no output schema, the description covers the essential scenarios, prerequisites, defaults, and edge cases. An agent has enough context to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds meaningful parameter context: port location depends on ssh, public=true disables the gate, expires controls key lifetime, restart yields a new URL, and idempotency affects the result. This goes beyond the schema's individual field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Publish an app that is already listening on a port to a public *.trycloudflare.com URL.' This clearly identifies what the tool does and distinguishes it from deploy-style tools by emphasizing the app is already running.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: local ports vs remote ports via SSH, and it explains the SSH prerequisite. It does not explicitly name sibling alternatives or say when not to use it, but the 'already listening on a port' framing provides enough guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every cloudfact deploy with backend, status and URL.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only safety profile is covered. The description adds the output fields but does not disclose pagination, ordering, or filtering behavior. The added context is minimal but not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys scope and output fields without any wasted words. Every part of the description earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only list tool, the description is nearly complete: it identifies the resource, scope, and returned fields. The only minor gap is the lack of an output schema and any mention of pagination or result limits, but the simplicity of the tool makes this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no input semantics to explain. The baseline of 4 applies because the description does not need to compensate for any undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb ('List'), a resource ('cloudfact deploy'), and the returned fields ('backend, status and URL'). It clearly differentiates from siblings like status, logs, or deploy which target individual deploys or actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the verb and scope ('List every cloudfact deploy'), but there is no explicit guidance on when to use this versus sibling tools such as status for a single deploy or logs for runtime output. The description leaves this inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Last lines of the deploy logs: host (local server), cloudflared and wrangler.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Deploy name | |
| lines | No | Number of lines (default 40) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile, and the description adds useful behavioral context by specifying which logs are included and that only the last lines are returned. However, it does not disclose any additional behavior such as ordering, availability of logs, or error conditions, so it stays at an adequate level given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous words. It immediately communicates the resource and scope, then lists the log sources. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two well-documented parameters and no output schema, the description covers the essential aspects: what the tool returns (last log lines) and which logs are included. It lacks only usage guidance and return formatting details, but these are less critical given the low complexity and schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (name and lines) with their meanings and defaults. The description adds no additional semantic detail beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource relationship: it retrieves the last lines of deploy logs. It further distinguishes itself from siblings like status or list by naming the three specific log sources (host, cloudflared, wrangler), so an agent can tell this is a log-reading tool rather than a status or listing tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus its siblings. It does not mention alternatives like status for deployment health or list for deployment names, nor does it describe prerequisites such as requiring an active deploy or prior deploy action. The agent is left to infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
File a deploy under a project in the account catalog (or pass project=null to clear it). Takes effect without redeploying.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Deploy name | |
| project | Yes | Project name, or null to clear |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and idempotentHint=true, establishing this as a non-destructive, repeatable mutation. The description adds useful behavioral context beyond those annotations: the change takes effect without redeploying. No contradiction with the annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with every clause earning its place: the core action, the null clearing behavior, and the no-redeploy effect. It is front-loaded and contains no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter setter with full schema coverage and helpful annotations, the description provides enough context to call the tool correctly. It does not describe return values, but the absence of an output schema and the simplicity of the mutation make that a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented with their types and meanings. The description adds minimal semantic value beyond the schema, only reinforcing that null clears the project, which the schema already states. A baseline 3 is appropriate because the schema carries the parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: file a deploy under a project or pass project=null to clear it. It is specific about the resource and operation, and the title 'Set project' reinforces the intent. It does not explicitly name sibling tools like deploy or catalog to differentiate from them, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Takes effect without redeploying' implies this is the tool to use when changing a deploy's project assignment without rebuilding or redeploying. However, the description never states when to choose this tool over alternatives such as deploy or catalog, leaving the usage context implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop (if running) and delete the deploy record and logs. On the workers backend, also deletes the worker on Cloudflare.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Deploy name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavior beyond annotations: it mentions stopping the deploy if running, deleting logs, and the Cloudflare worker deletion. This goes beyond the destructiveHint flag and provides concrete side effects. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences that front-load the primary action and then add a specific backend nuance. No wasted words, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter destructive tool with no output schema and annotations covering safety, the description covers all necessary aspects: what is deleted, the conditional stop, and the backend-specific behavior. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully covers the single parameter 'name' with description 'Deploy name' (100% coverage). The description adds no additional detail about the parameter's format, constraints, or semantics beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Stop (if running) and delete the deploy record and logs.' It also adds the specific Cloudflare worker deletion for the workers backend. This distinguishes it from sibling tools like 'stop' (which only stops) and 'deploy' (which creates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for full removal, but it does not explicitly say when to use it versus alternatives like 'stop' or 'list'. It does not mention that it is destructive or that it should be used only when permanent deletion is intended. The destructive hint is in annotations, but the description itself lacks explicit usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Issue a new private key for a live tunnel deploy without restarting it: the previous link and all sessions stop working at once. Optionally set an expiry. On a public deploy this turns it private. Returns the new privateUrl.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Deploy name | |
| expires | No | New key lifetime, e.g. "24h" (default: never) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say the tool is mutating and non-idempotent, so the description carries the burden of explaining effects. It does exceptionally well by disclosing that previous links and all sessions stop working immediately, that no restart occurs, and that public deploys become private. This is substantial behavioral context beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three compact sentences: core action and consequence, optional expiry, and public/private behavior plus return value. Every sentence earns its place and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema, the description covers the key behavioral consequences, the special public-deploy case, and explicitly states the return value (new privateUrl). Combined with the high-quality schema, an agent has enough context to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema gives 100% parameter coverage, including the 'expires' format and default. The description only adds that expiry is optional, which is useful but not a major semantic addition beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Issue a new private key for a live tunnel deploy') and immediate consequence ('previous link and all sessions stop working at once'). This clearly differentiates it from siblings like deploy or expose, even without naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: to rotate credentials on a running tunnel without restarting, optionally setting an expiry, and to convert a public deploy to private. It doesn't name alternatives or explicit exclusions, but the context is strong enough for an agent to make the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
State of one deploy, including an HTTP check of its public URL (reachable/httpStatus).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Deploy name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations only declare readOnlyHint=true, and the description adds a meaningful behavioral detail: it performs a live HTTP check of the public URL and reports reachability/status. This warns the agent that the operation is network-dependent, going beyond the read-only safety signal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the resource scope and the key behavioral qualifier (HTTP check). There is no filler or redundant restating of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one required parameter and no output schema, the description provides enough for correct invocation: it identifies the deploy and what result will be reported. It names the main returned fields (reachable/httpStatus), though it does not enumerate all possible states.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the only parameter, 'name', with the description 'Deploy name', so the tool description adds no additional parameter meaning. With 100% schema coverage, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as 'one deploy' and its state, which distinguishes it from broader operations like list. It also names the concrete output aspect ('reachable/httpStatus') from an HTTP check. It lacks a strong imperative verb but is specific enough to separate it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by 'State of one deploy' — the agent can infer this is for checking a single named deploy. However, there is no explicit guidance about when to prefer it over siblings like list or logs, nor any mention of edge cases such as unreachable URLs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop the local server and tunnel of one deploy (or all of them with all=true). The record is kept for inspection. Not applicable to the workers backend.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Stop every tunnel | |
| name | No | Deploy name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false; the description adds context by specifying exactly what is stopped (server and tunnel) and that the record is preserved for inspection. It also notes the backend limitation, which is beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with the core action front-loaded. Every phrase adds value: the action, the 'all' option, the record retention, and the exclusion. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation with two optional parameters and no output schema, the description covers purpose, side effect (record kept), and a usage exclusion. It does not describe reversibility or return behavior, but these are minor for a stop operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents both parameters (all and name) with descriptions. The tool description references 'all=true' but adds no new meaning beyond what the schema provides. Given 100% schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (stop) on a specific resource (local server and tunnel of a deploy) and includes the 'all=true' option to stop all deploys. This distinguishes it from siblings like 'remove' (destructive) and 'status' (inspection).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit exclusion ('Not applicable to the workers backend') and implies the use case by describing what it does. However, it does not explicitly name alternative tools or contrast with 'remove' beyond stating the record is kept, which hints at non-destructiveness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.8.8catalogcredentialsdeploy3 fields changedInput schema / properties / accessAdded value: +{
+ "description": "Emails allowed to sign in through Cloudflare Access (identity gate instead of the key link; workers backend)",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / privateRemoved value: -{
- "description": "Key-protected: only whoever opens privateUrl (#key=...) sees the content. Forces the tunnel backend",
- "type": "boolean"
-}Input schema / properties / publicAdded value: +{
+ "description": "Publish without the key gate (default false: private)",
+ "type": "boolean"
+}projectv0.5.0deploydoctorexposelistlogsremoverotatestatusstopScored across 12 tools
Each tool targets a distinct action/resource: static deploy vs port expose, local records vs account catalog, stop vs remove. Potential pairs like list/catalog and deploy/expose are clearly separated in their descriptions.
All names are single lowercase words, giving a clean CLI-like style. There are minor semantic shifts between imperative verbs (deploy, remove, rotate) and noun-style commands (status, credentials, logs), but no mixed casing or inconsistent formatting.
Twelve tools cover static deploys, port exposure, local lifecycle management, account cataloging, credentials, logs, and diagnostics without bloat. Each tool has a clear role in the deployment workflow.
The surface covers the main lifecycle: create/deploy, expose, inspect, log, stop, delete, rotate, and organize. Minor gaps exist such as no explicit post-creation public/private toggle or access-list update on existing deploys, but agents can usually work around them via redeployment.
Secure tunneling, reverse proxy and remote access for local applications.
Get share links, publish and manage websites, artifacts and agents. No account needed.
Publish files and folders to the web instantly: permanent URLs, immutable versions, claim links.
Publish a single HTML file as a live HTTPS site in seconds. Versioned deploys, no delete tool.