Add tools to your app

An app can also be an MCP server: a set of tools an AI client calls on the buyer's behalf. You add them to the app you are already publishing. There is no separate kind of listing, no second price and no second purchase. Buyers see an App + MCP label and an MCP chip on the card, and the tools are included in the one price.

Adding tools is opening in stages. If your submission is refused with code: "tools_not_open", tools are not switched on for the environment you submitted to yet. Nothing was created.

What you add

Put a panoply.tools folder in your zip (or at the root of your repository), next to your app, with two files:

• tools.json, the manifest: what the tools are.
• tools.js, one ES module under 1 MB: what they do.

An app without a site is not accepted (site_required): the tools belong to an app that has a page and screenshots like any other listing.

The manifest

{ "schema": 1, "capabilities": ["storage"], "tools": [ { "name": "build_set", "title": "Build a set", "description": "Builds a DJ set from the buyer's library.", "inputSchema": { "type": "object", "properties": { "minutes": { "type": "integer" } } }, "annotations": { "readOnlyHint": false } } ] }

At most 40 tools. Unknown extra fields are allowed.

When the manifest changes

Additive changes (a new optional field, a new capability) keep schema: 1. A breaking change gets a new number, and the old number keeps working for six months after the new one ships. Panoply emails you on the day a newer number ships and again 30 days before the old one ends. After it ends, the tools part of a listing still on the old number stops answering with tools_schema_expired, while the app itself keeps working and stays listed. Resubmit on a supported number to bring the tools back. A submission on a number that is not supported is refused with tools_schema_unsupported, naming the supported ones.

The code

tools.js exports one function per tool, as named exports or as a default-exported object. Each receives the tool's arguments and a ctx:

export default { async build_set(args, ctx) { const library = (await ctx.panoply.storage.get('library')) ?? [] return { tracks: library.slice(0, args.minutes) } }, }

A tool returns a JSON value (under 1 MB; write anything larger to a file). If it throws, the caller sees the error text.

Your code never holds a key, a token or a binding. It runs in an isolate with no network access: fetch, sockets, eval and dynamic import() all fail. Everything it can reach is through ctx.panoply, and every call is scoped to one buyer and this one app. A method for a capability you did not declare refuses with capability_not_declared.

Whose data a tool acts on

When a buyer's tools run, they act on that buyer's data. When an agent calls the tools for a custodian who connected it to the app, the tools act on the custodian's data, and every row they write is labelled with the agent as the actor. An agent that bought the app for itself acts on its own data.

Limits

Long-running tools and jobs

A tool that runs for minutes is declared "long": true (with the jobs capability). Calling it does not wait: it answers within a second or two with { job_id, status: "queued", poll_after_ms }, and the work runs as a job in the background. Panoply adds four tools to every listing for this, so the caller can follow it: get_job (status, progress, the result, the files it wrote), list_jobs, cancel_job and get_file_link (a signed link to read a file, valid for five minutes, which supports ranged requests so audio and video can seek).

In a long tool, ctx.panoply.job.progress(fraction, message) reports progress (a number from 0 to 1 and a short note) and ctx.panoply.job.cancelled() tells you whether the buyer cancelled; once a job is cancelled, ended, or the buyer stops holding the app, every other ctx.panoply call is refused (job_cancelled, job_ended). Files a job writes with files.put are listed on the job, and count in the buyer's quota like any file. Print with console.log as usual; if the job fails, the last 4 KB of that output and the error are kept for the buyer, never for you.

The buyer's page can use panoplyJobs.list(), panoplyJobs.get(id) and panoplyJobs.cancel(id). If the Key Vault is briefly down, a job's step is retried; if the buyer's access ends (a refund, or a revoked connection), the job ends not_entitled at its next check, at most 30 seconds later.

A job can run more than once. A retried step runs your handler again from the start, so write it to be safe to repeat.

How it is scanned and reviewed

The scan reads tools.js as code, not as text. It checks that every tool in the manifest has a handler and that no handler is missing from the manifest, and it flags network calls, dynamic code, imports and host objects. It checks tool names and descriptions for instructions aimed at the AI client, and for tools that do more than they say. A tool that cannot be read statically is flagged, never passed.

Then a person at Panoply reads every tool: its description, its schema and what it can reach, and marks the bundle seen. Approval waits for that. If you change tools.js after the scan, the listing needs a fresh scan and a fresh read. Buyers see the tools and what they can reach on the listing before they buy.

Testing your tools

You cannot read what a buyer's tools did with their data, and neither can Panoply's reviewers: a failed run's log is kept for the buyer alone. Debug by running your tools on your own account. You hold your own listing, so you are a buyer of it, and a failure there shows you the log.

If your licence includes the source

For a listing under the source-included or open licence, buyers who hold the app can download tools.js from GET /api/apps/{slug}/tools-source. Under use-only it stays private. This is the tools only: the app's own source is a separate matter.

Refusals you can meet