Modules and script apps
Add a service to Jade with a JSON file: a link to an MCP server, or a few small scripts.
Two kinds
- Module (a service)
- A JSON file that points to a service’s remote MCP server and says how to sign in. It has no code. The person adds it, signs in, and its tools join every chat and task.
- Script app
- A JSON file with a few small JavaScript tools that run on the person’s device, in Jade’s sandbox. No server needed. Each kind of access it asks for is a permission the person answers Ask first, Allowed or Blocked.
Both are published the same way, listed in the same catalog (the Apps screen’s service list), and added with a link. The full field-by-field format, the JSON Schema and a form to try it are on the marketplace API page. This page is the walk-through.
A service in five minutes
- Find the MCP server. The service has to offer a remote MCP server over Streamable HTTP (or HTTP+SSE) at an https address. A server that only runs locally (stdio) can’t be reached from a phone: put an MCP proxy in front of it.
- Pick how to sign in. Either a token the person pastes (
server.headernames the header,Authorizationas a bearer token by default) or OAuth ("auth": "oauth"; Jade finds the sign-in service from the server and uses PKCE and dynamic client registration). - Write the file.
{ "id": "acme", "name": "Acme Tasks", "publisher": "Acme Inc.", "category": "Productivity", "blurb": "Your Acme tasks and projects", "symbol": "checklist", "server": { "url": "https://mcp.acme.example/mcp" }, "token": { "name": "API key", "page": "https://acme.example/settings/keys", "steps": ["Open Acme's key page and sign in.", "Create a key named “Jade”.", "Copy it."] } } - Check it. Test it against the schema before publishing:
curl /v1/services/schema -o module.schema.json # then validate acme.json with any JSON Schema tool
- Publish it.
Save the edit token. It is shown once, and it is the only way to update or remove the module.
curl -X POST /v1/services \ -H 'content-type: application/json' -d @acme.json # {"id": "acme", "status": "pending", "editToken": "jsm_…"} - Share the link.
jade://module?url=https://example.com/acme.jsonopens Jade’s add screen for it, wherever the file is hosted, even before it is listed.
The token is sent only to the module’s own server, and only over https. Jade shows where a module connects before it is added, and keeps it only after the person confirms.
Review and updates
- A new module is
pendinguntil the server’s operator approves it. Onlylivemodules are listed. Check progress withGET /v1/services/<id>/statusand the edit token; a rejected module has a note explaining why. - A publisher key (
jpk_…, made by the operator withjade keys create, limited in time) skips review and has its own hourly limit. Send it asAuthorization: Bearer jpk_…on the POST. - An update is a PUT of the whole file with the edit token. Text changes (blurb, about, abilities, category, symbol, color, token steps) stay live. Changes to the name, publisher, server, sign-in or token page go back to review, and the approved version stays listed until then.
- Limits: 64 KB a file; 5 submissions an hour per address and 10 waiting at a time.
Script apps
A script app has script instead of server and token. Each tool is the body of an async function of args; what it returns is the result the model sees.
{
"id": "tip",
"name": "Tip Splitter",
"publisher": "Me",
"category": "Scripts",
"blurb": "Split a bill with a tip, exactly",
"symbol": "dollarsign.circle",
"script": {
"tools": [{
"name": "split",
"description": "Split a bill between people with a tip percentage.",
"parameters": [
{ "name": "bill", "type": "number", "description": "The total before tip" },
{ "name": "tip_percent", "type": "number", "required": false },
{ "name": "people", "type": "integer", "required": false }
],
"code": "const tip = (args.tip_percent ?? 18) / 100; const n = args.people ?? 1; const total = args.bill * (1 + tip); return `Total ${total.toFixed(2)}, ${(total / n).toFixed(2)} each for ${n}.`;"
}],
"network": false
}
}What a script can reach
The jade.* object in a script reaches the phone, but only through permissions the app declares in script.permissions. Each is one of calendar, reminders, contacts, photos, location, notes, shortcuts, models, web, clipboard, notifications, tools, network, scan, files, chat, session, window and media, with read or change access. network is jade.fetch, an HTTPS request from the phone; its domains list (up to 20, like api.example.com or *.example.com) names the sites the app may reach without a question, and any other site asks once per run. session lets the person sign in to the sites its domains list (at least one), and the app then acts as them there; it always starts as Ask first. When the person adds the app, each one is set to Ask first, Allowed or Blocked, and a blocked one simply isn’t available. Every tool run also asks first, unless the person turned on the app’s “runs quietly” entitlement.
- Entitlements
- Go past the usual limits, and the person switches each on or off:
highVolume,longRuns(up to 10 minutes),anyNetwork,moreStorage(8 MB),runsQuietly,webSearch,anyModel. - Cards
- An app can ship up to 8 cards: HTML templates with
{{field}}placeholders that Jade shows in the chat withjade.cards.show(name, data). They run in a web view with no network. Showing one needs no permission. - Settings page
script.settingsgives the app a page of its own with switches, choices, text and number rows, and blocks of its own HTML. The person finds it on the app’s page and under Settings → Apps & tools → App settings; the code reads the values withjade.settings.- Setup screen
script.setupopens a screen when the app is added: the settings rows plussecret(kept in the Keychain),signin(the site’s own sign-in page in a window; thesessionpermission has to cover its host) andrequired. An optionalchecktool tries what was entered. Until every required row is done and the check has passed, the app shows Needs setup and its tools say what is missing.- Local server
script.servermaps up to 24 routes to the app’s own tools, for interactive cards to call. It runs inside Jade on the device: there is no network server.- Windows
script.windowsgives the app full-screen pages of its own (HTML, CSS, JavaScript, WebGL, audio) that run on the device with the app’sjade.*object. It needs thewindowpermission. Each window gets a toolopen_<id>and each of its own tools becomes<id>_<name>, which the assistant can call while the window is open. The pages come fromscript.bundle(a.tar.gzwith an https address and a SHA-256, downloaded and checked when the app is sent in) and/orscript.files(up to 40 small text files, 48 KB in all). A window is code like a tool: review reads its pages, and a changed bundle or file is a changed app.- Web search hook
script.webSearchnames a tool Jade calls before every web search, so an app can pick the engine or filter domains. It needs thewebSearchentitlement.
Every function with its signature, return value and limits is in the jade object reference. Exact rules for the file, such as names, sizes, and which permissions can change, are on the marketplace page. Any change to a live script app’s code goes back to review, because the code is what the operator reads before approving.
Writing a good one
- Describe tools for a model. The
descriptionis how the model decides when to call a tool: say what it does and what it returns, in a sentence or two. - Ask for the least. A permission that isn’t needed makes people hesitate. Give each a short
reason. - Return text a model can use. Short and structured. Not a megabyte of JSON.
- Say what failed. Throw an error with a plain message. The model reads it and tries something else.
- Mark reads as reads. For a server, an MCP tool that only reads should say
readOnlyHint, so Jade treats it as low risk. Anything else asks first.
The wider list of what Jade speaks is on For developers, and every call in the API reference.