Skip to main content
Glama

Publish a Hosted App

publish_app_version
Destructive

Publish a static Hosted App immediately at /projects/{pid}/apps/{slug}/ and return its absolute URL. Publish is final: members with access see it now. A first publication requires name. Only a verified human Administrator of this Project may publish; a taken slug you cannot manage answers slug_unavailable. The first version starts Administrators-only; share it with Roles through set_app_access. Inline scripts and styles are allowed; declare every external HTTPS origin in external_hosts (HTTP only on loopback). The app is served on its own host. It calls only the Requests its current version records, plus those listed in calls_without_grant, using plain fetch of GET /api/data/v1/projects/{pid}/catalog and POST /api/data/v1/projects/{pid}/requests/{request_id}/execute on that host. Execute with Accept and Content-Type application/json and {"parameters": {...}}; never embed bearer tokens in app files. Publishing records the approved Requests the version calls: those in requests plus any Request UUID found in its files, except calls_without_grant, which are never recorded; strict_recording: true records only declared Requests. The Roles the app is shared with reach those Requests everywhere, so sharing an app is the grant. Returns requests (declared, scanned, recorded, calls_without_grant, mode) and access_changes; identical content answers unchanged: true. files[].sha256 is each file's own SHA-256; content_hash digests the whole version. Publishes the union of this publisher's staged area and inline files; inline files win on the same path, and files may be empty when files are staged. A refusal preserves the area for correction and retry. A successful publish consumes the whole area, including an unchanged publish. To republish, pass base_version_id (the current version), send only the changed paths in files and name deleted paths in remove_paths, or change a file without resending it: edits whose old_string appears exactly once, guarded by expected_sha256. Inspect staged sizes and published versions after an uncertain response before retrying: compare list_apps({}) current_version_id and list_app_versions include_files: true (files, entry, manifest); if a later publication is current, report it; never reactivate the old version, and keep the original base_version_id on a retry. Read describe_hosted_app_publishing before writing an app that calls Requests, confirms actions or stores data, or before retrying after an uncertain response, and when a refusal names it: the HTTP contract, error codes, stream_status, confirmation screens, recording, staging and edits. See request_app_upload_url for shared upload limits, chunking, expiry and staging lifecycle rules.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "slug": "<slug>"
    },
    "name": "publish_app_version"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoRequired on first publish; omitted on republish retains the current name
slugYes1–64 lowercase letters, digits and internal hyphens
editsNoIn-file text replacements {path, old_string, new_string, expected_sha256?} applied in order after base, staged and inline files, each old_string appearing exactly once in a text file; accepts an array or JSON string.
entryNoEntry file path; default index.html
filesNoInline files: {path, content, encoding?: utf8|base64, content_type?}; [] is allowed when files are staged. Type inferred from extension when omitted. For a recognized extension, explicit content_type must match; otherwise an explicit allowed content_type is required. Allowed types (extension: content_type): .cjs: text/javascript; .css: text/css; .csv: text/csv; .gif: image/gif; .htm: text/html; .html: text/html; .ico: image/x-icon; .jpeg: image/jpeg; .jpg: image/jpeg; .js: text/javascript; .json: application/json; .md: text/markdown; .mjs: text/javascript; .otf: font/otf; .pdf: application/pdf; .png: image/png; .svg: image/svg+xml; .ttf: font/ttf; .txt: text/plain; .wasm: application/wasm; .webp: image/webp; .woff: font/woff; .woff2: font/woff2. PDFs are served as downloads: an app fetches their bytes to process them, and they cannot be shown inline. The union permits at most 500 files, 5242880 decoded bytes each, 52428800 decoded bytes total; the smaller MCP request-body ceiling still applies. Accepts an array or JSON string.
requestsNoRequest UUIDs this page calls. Each must be an approved Request of this Project. UUIDs found in the files are recorded too unless strict_recording is true. List a Request the page calls but sharing must not grant in calls_without_grant instead.
descriptionNoApp description; omitted retains the current description
remove_pathsNoRelative paths to drop from the base version. Each must be a path the base already holds and must not also be sent in files or staged. Accepts an array or JSON string.
setup_step_idNoOptional setup step UUID this call fulfils (Administrator only). Pass a planned entry you recorded, or the id of the step this Project already opened for the same component. Otherwise the same MCP session's oldest unbound plan of this kind matching its subject hint is used, otherwise a new entry opens. A committed creation whose journal binding fails still succeeds with a warning naming this entry; do not repeat creation.
application_idNoOptional app draft UUID in this Project, bound on first publication so its Application and Hosted App share it; omit on republish.
external_hostsNoAt most 32 HTTPS origins, without paths; accepts an array or JSON string
base_version_idNoStored version UUID to start from, so only changed paths need to be sent. Must be this app's current version; omitted publishes exactly the staged and inline files.
strict_recordingNotrue records only declared Requests, refusing the publish with hosted_app_request_undeclared when its files call an approved Request that is neither declared nor in calls_without_grant; omitted or false is scan mode, and requests.mode answers strict or scan.
calls_without_grantNocalls_without_grant lists Request UUIDs this page calls that sharing never grants, so only a viewer who already holds one can run it; omitted on a republish keeps the current list and [] clears it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true, readOnlyHint=false and idempotentHint=false, but the description adds substantial context beyond them: Administrator-only authorization, slug_unavailable refusals, Administrators-only first version, external_hosts/origin restrictions, the staging-area consumption semantics, and the rule that an unchanged publish still consumes the area (which is consistent with idempotentHint=false). It even sketches the return payload (requests, access_changes, unchanged: true) despite no output schema, though it is less explicit about rate limits or partial-failure states.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and URL are front-loaded, which is good, but the remainder is an undifferentiated wall of text mixing failure codes, HTTP contract details, recording rules, retry procedure and parameter echoes. Most sentences carry real information, yet several (edits matching, remove_paths restrictions) duplicate the input schema and could be cut to improve scanability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter destructive mutation with no output schema, the description covers authorization, idempotency behavior, error responses, the shape of the returned object, and a recovery path for uncertain responses (inspect list_apps and list_app_versions, keep the original base_version_id). An agent has enough to call it correctly and to recover from failure without external documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description contributes cross-field meaning the schema cannot express: publishes the union of staged and inline files with inline winning on the same path, files may be empty when files are staged, base_version_id must be the app's current version, and strict_recording vs scan mode changes how UUIDs found in files are recorded. Some sentences restate schema text (edits matching exactly once, remove_paths constraints), which keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource plus the exact resulting location: 'Publish a static Hosted App immediately at /projects/{pid}/apps/{slug}/ and return its absolute URL.' It also names the sibling it depends on (describe_hosted_app_publishing) and the access tool used afterward (set_app_access), so the agent can place it without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use conditions: first publication requires name, republish requires base_version_id, send only changed paths in files and deleted paths in remove_paths, and consult describe_hosted_app_publishing before writing an app that calls Requests or after an uncertain response. It does not exclude itself against other version-admin tools like set_app_current_version or delete_app_version, so it stops short of full alternative routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources