Using plugins

A plugin brings capability from outside Mosael in — a local script, or an existing MCP server. Once wired in, its tools work in both the agent and workflows, with no second adaptation for either side.

A process plugin runs as its own child process with a minimal environment: PATH / HOME / LANG plus the credentials it declared. This limits what Mosael passes to the process; it is not an operating-system sandbox. A local plugin runs with your user permissions and may access files and network resources available to you.

Want to write one? See Writing a plugin.

Two kinds#

	Local script	MCP server
Declared as	entry pointing at a Python script	kind: "mcp" plus an mcp block
Tool list	written in the manifest's tools	pulled from the server, never transcribed
Good for	pure computation, a simple one-shot HTTP call	a platform that already ships an MCP server

Package / connection / capability#

• A package is what sits on disk: a directory plus a manifest.
• A connection is one concrete hook-up: some config, some credentials, a name, an on/off switch. One package can be connected several times — TikHub is one package covering a dozen platform endpoints, so you might have one connection for Bilibili and another for Douyin, each with its own key.
• A capability is which tools that connection exposes. You tick them one by one, and none are on by default.

The page lays those three out left to right: the Installed column is packages, the top right is this package's connections, and below that are the tools that connection exposes. Nothing on by default is deliberate — an MCP server routinely reports dozens of tools, and turning them all on drowns the node panel and the agent's tool list. A model picking from forty names picks wrong more often, not less.

At the top right is the plugin's header: its name, status (Built in / Installed / Update available), a one-line summary, the version and author (a link when there is one), with New connection and Docs on the right and Uninstall under ⋯; when there is a newer version an Update button opens its page in the market. Below the header are two tabs: Connections (the default) and About — what it does, the introduction, tools, permissions and plugin ID, the same overview as its detail page in the market.

Connections collapse. When a package has several connections (a few ComfyUI servers, TikHub for several platforms), each card can fold into one line: the name, the key address (such as the server URL), the state (Ready, Off, Error, Needs permission…), how many tools are on and the usual actions all fit in it. Anything that needs you (re-authorization, missing settings) is flagged even when folded, and expanding goes straight to it. A single connection starts expanded, several start collapsed, and a new one opens expanded; which ones are folded is remembered on this device, and the Connections tab row has Collapse all / Expand all on the right.

Errors lead with a plain sentence. The error on a connection's title row and the reason the generation models row couldn't refresh show only their first line — what happened and what to do next; the address, errno and other raw text are in the hover hint (with the connection folded, hover its title row: the raw text comes first, then the offer to expand), or under Details on the page. The error follows the viewer's interface language — including ones recorded during a background refresh — and changes with it.

Installing one#

The left column of the Plugins page lists installed plugins; the header has Scan plugins and Browse plugins. The market is a grid of cards: search at the top (tool names count too), filter by All / Installed / Updates, and Filter by capability — noise reduction, transcription, translation, speech, document parsing… only those some plugin in the market actually provides, each with a count. A card opens a detail page: the header has the name, status, a one-line summary and what you can do (Install, Update, or Manage for one that is installed — it opens it on the Plugins page — plus Docs); below, What it does gives each capability a tile saying where it shows up once installed; the introduction is folded to three lines with Show more; tools are one per row with a two-line description; and the right column groups permissions by kind — network, files, programs — in plain words (hover one for its code).

From the market: find the one you want and hit Install. It does not go straight in — the package is fetched, its manifest read, and the permissions it declares (grouped by kind) and the tools it brings are laid out for you before anything lands; Docs at the bottom left shows how it is used first. Installing a plugin puts code that will be executed on your machine; that list is worth a look.

Built-in plugins (ComfyUI, Object Storage and MinerU document parsing) show up in the market too, marked Built in: they are already installed and update with the app (the header says Updates with Mosael), so there is no Install button and they cannot be uninstalled — hit Manage to open it on the Plugins page and add a connection to start using it.

From a link: any zip URL works, through the same confirmation. A company intranet can host its own market index (plain JSON — format in Writing a plugin) and point the app at it in settings.

By hand: copy the plugin directory into the plugins folder (the Plugins page tells you where — don't go looking for ~/.mosael/plugins, that path does not exist on Windows) and hit Scan plugins. This is the fastest loop while writing one.

Once installed: a package with no settings comes with a connection ready to go, one with settings needs you to add a connection; the permissions the manifest declares are granted one at a time, and an ungranted connection stays unavailable.

When an update asks for more permissions, existing connections are switched off first — their models and tools are unavailable for the moment, instead of quietly gaining access. The top of the connection card says why, and which permissions were added; Grant these N restores it at once, and what you granted before stays. The plugin list marks it Needs permission.

Uninstalling removes the plugin directory from disk along with its permissions, credentials and call log. Clearing only the records is not enough — the next scan would install it right back, and what the user sees is "I deleted it and it came back". Deleting the directory by hand also clears the record on the next scan.

Credentials#

The manifest's credentials block declares which secrets are needed. You fill them in on the Plugins page and they are injected into the plugin's own process at run time.

Mosael does not inject its own provider secrets or API session token into the plugin environment. Local plugins still run with the current user’s operating-system permissions, so install trusted code and review the tools and permissions it declares.

A plugin missing a required credential stays out of the tool list — letting the agent call a tool that is certain to 401 only burns a turn restating what the settings page already said.

Each connection also carries two settings that come from the host:

• Network: Follow Mosael (the default — the outbound proxy under Admin → Deployment), Direct (no proxy), or Use a proxy with an address. MinerU, for instance, only serves mainland China: from abroad pick a proxy into the mainland; inside China with a global proxy on, pick direct.
• PyPI mirror / npm registry: only for plugins that install dependencies (Manim, Remotion); they follow Admin → Engines → Download sources by default, or pick a preset or custom address per connection.

The proxy environment variables (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY and friends) are injected by the host from this setting; a plugin manifest can't declare them itself.

Letting it do the OAuth for you#

A plugin that needs OAuth tokens (cloud drives, photo services) can declare an oauth block. When it does, the first row of each connection is Authorization: next to the title it says whether the connection is Not authorized, Authorized or Needs re-authorization, with an Authorize button on the right (Re-authorize once it has been done). Fill in the app credentials such as the AppKey and SecretKey, click it, sign in on the provider's page, and paste the code it gives you into the Authorization code row that appears below. The tokens land in the right credential fields on their own.

The fields the authorization fills (a Refresh Token, an Access Token) are not laid out as main inputs next to the AppKey; they belong to the Authorization row. If you already have tokens, click Enter tokens manually to open them up below it and fill them in yourself.

When the provider stops accepting the stored tokens (the refresh_token was revoked, the app was disabled), the connection is marked Needs re-authorization — run Re-authorize once and it is back.

The step that cannot be automated is registering an app to get the AppKey / SecretKey — that is between you and the provider's developer console. What can be automated is everything after: assembling the authorization URL, exchanging the code for tokens, and knowing which fields to store them in. Get any of those slightly wrong by hand and what comes back is invalid_client or similar — an error that never says which box was wrong.

Why you still paste a code. The callback does not use a custom protocol (any web page can fire one of those), and it does not open a listening port on your machine (the redirect URL has to be registered in the provider's console up front, and a local port changes). One extra paste buys a path with nothing forgeable on it.

Tokens renew themselves: when the plugin hits an "expired" error it fetches a new token, retries the call once, and hands the new token back to be stored. Providers often return only an access_token on refresh — fields they did not return are left alone, because writing a blank over an existing refresh_token would destroy it, and losing that one means authorizing all over again.

The manifest syntax is in docs/PLUGIN_MANIFEST.md, under instance.oauth.

In the agent#

Tools from an enabled, authorized, fully-credentialed plugin appear directly in the agent's tool list (named plugin__<plugin>__<tool>), indistinguishable from built-in ones. The model sees the name and the input schema straight away — it does not have to first think of asking whether a plugin might help, then spend a turn listing them.

Why tools are off by default: an MCP server may report forty or a hundred tools. Exposing them all makes the node panel a forty-row haystack, costs tokens on forty descriptions every turn, and crowds out the model's choice among the built-in tools. The tool list on the Plugins page is searchable (names and descriptions both match) and can be toggled in bulk over the current filter.

Tools with consequences ask first. Every tool declares its effects: nothing outside, costs money, acts outside the app, or runs code on this machine. When the agent (the in-app assistant, or an MCP client such as Claude CLI) calls a plugin tool that costs money, acts outside or runs code, a confirmation card comes first, naming the tool, the connection, a parameter summary and why it asks (e.g. "runs code on your computer"); once approved it runs with your own connection. Read-only tools still run directly. Those tools carry an Asks first badge in the tool table and the market. A tool that declares nothing counts as acting outside.

Sub-agents get no plugin tools by default. A sub-agent only uses read-only tools, and a plugin tool with no confirmation gate can still send requests or write files. To allow one, mark it "read_only": true in the manifest — that is a judgement made by whoever ships the plugin, not something the plugin gets to claim about itself. Same for MCP plugins: override by name under the manifest's tools. That is not a second tool list; only the read_only key is read from it.

Tools & call log#

• Tools: the panel lists each tool; fill in parameters and try it in place.
• Call log: recent calls are recorded (success / failure + input & output), expandable per entry; delete one or clear all.

In workflows#

Every plugin tool is a node, each on its own row under the Plugins group of the Add Node panel. It behaves like any built-in node — same form, same inputs and outputs, same validation — and the form is generated straight from the tool's input schema.

A plugin can also declare what its node looks like (label, description, form, output sockets), along the lines of ComfyUI's custom nodes. The syntax is in docs/PLUGIN_MANIFEST.md, under workflow nodes.

Export a workflow to a machine that lacks the plugin and opening it tells you exactly which tool of which plugin is missing.

Plugins that work for Mosael#

Some plugins don't offer tools to the agent and workflows; they generate for Mosael instead. Such a plugin lists its models (the parameters each one takes and its reference image slots), and those models appear in the model pickers of AI Studio, boards and workflows exactly like a built-in provider's. Generation runs as the same kind of task — progress and cancel in the task center, outputs in the asset library, usage recorded as usual.

ComfyUI, which ships with Mosael, is one of these: it is on the Plugins page from the start and can't be uninstalled (switch its connection off if you don't use it). See Generating with ComfyUI for setup. The connection card of such a plugin shows “N … · refreshed …”, in the plugin's own word for what it hands over (workflows, for ComfyUI); after saving a new workflow in ComfyUI, click “Refresh workflows”.

A plugin can also give a connection libraries: a ComfyUI connection's title row has two icon buttons, Open model library and Open workflow library, showing the server's model files and saved workflows — previews, downloading missing models, importing workflows from elsewhere and installing missing node packs all happen there; see Generating with ComfyUI.

Plugins can also register in Mosael's capability table, side by side with the local engines: document parsing, noise reduction, vocal separation, transcription, translation, speech and asset links. Install one and it appears under that capability in Settings → Capability providers (where it can become the default), as well as in workflow engine dropdowns, the editor, the media library and the agent, used whenever it's named. A tool that claims a capability isn't hidden: it sits in the Plugins page's tool table with a badge for the capability, and expanding it shows where else it's used (MinerU's Parse a document with MinerU, for example — a document's Parse again and the Document to Markdown node call it too); tick it and the agent and workflows can call it directly. A plugin that only works behind the scenes and exposes no separate tools says on the Plugins page which jobs it does.

Examples#

These live under plugins/examples/ in the repository — examples and official plugins at once:

• text-toolkit — pure functions, no dependencies, no credentials: word count, extract hashtags, split into subtitle lines, shorten to a length, tidy up copy, Markdown to plain text, extract links and mentions — all local and read-only.
• tikhub — an MCP service with zero code: one package, one connection per platform, each with its own key; the tool list comes live from TikHub's MCP server. Reads public data from Douyin, TikTok, Xiaohongshu, Bilibili, Kuaishou and more.
• baidu-pan — the one with OAuth: it runs the authorization itself and renews its own tokens, and it shows how to hand a large file to the host to download (the plugin only resolves the URL; progress, cancellation and retries belong to the host).
• blender — talks to a Blender running on this machine. It wraps the existing MCP add-on as a plugin and declares each tool as read-only or writing (inspecting the scene and its objects only read; editing the model writes), so you decide per tool what the agent may do on its own and what needs your confirmation.
• remotion — animation from code, at no generation cost: lesson explainers, formula walk-throughs, code demos, data charts. Give it content and it renders an explainer (formulas typeset with KaTeX, code revealed line by line); write a Remotion component for anything freer. It also shows how a plugin declares its own time budget and keeps hundreds of MB of dependencies in a data directory that survives updates. Needs Node.js 18+; Remotion is free for individuals and companies of up to 3 people, larger companies need its company license.
• manim — teaching animations with Manim (the community edition of 3Blue1Brown's maths animation engine), at no generation cost: derivations, geometry, function plots, algorithm steps, code walk-throughs. See “Manim teaching animations” below.

Object storage (built in)#

The Object Storage plugin ships with Mosael and is on the Plugins page from the start. It closes one concrete gap: Mosael is local-first, so your assets live on your own disk with no public address, while some providers only take a URL — Seedance's reference video is one (a reference image may be Base64, a reference video may not). It uploads the asset to your own bucket and hands back a time-limited direct link (the signature lives in the query string, so the bucket need not be public-read).

1. Under Object Storage on the Plugins page, create a connection and pick the provider: Alibaba Cloud OSS / Tencent Cloud COS / Volcengine TOS / Amazon S3 / S3-compatible (MinIO, Cloudflare R2, …). One connection is one bucket; create one per bucket.
2. Fill in the bucket, region and an access key pair (use a sub-user scoped to this bucket, not the root account). The endpoint is usually left empty and built from the region; an S3-compatible service needs its own address (e.g. http://localhost:9000). Tencent bucket names carry the APPID suffix.
3. Grant its network permission.

From then on, when a generation input only accepts links and you gave it a local asset, the asset is uploaded automatically first; with several buckets, pick the default under Settings → Capability providers → Asset links. The same asset reuses its link until it expires. It is also a set of ordinary tools: upload (large files go up in parts, with progress), sign a link for an existing object, list a bucket, and pull an object back into the library.

The former Alibaba Cloud OSS / Tencent Cloud COS / Volcengine TOS / Amazon S3 plugins have been merged into it: on upgrade their connections, keys, permissions, default choice and workflow nodes move over as they are — nothing to set up again.

MinerU document parsing (built in)#

Scans, image-only PDFs, multi-column layouts and documents full of formulas and complex tables go to MinerU: layout analysis, OCR, table and formula recognition — far better than local parsing for these.

1. Create an API token under "API management" on mineru.net.
2. Enable MinerU document parsing on the Plugins page, add a connection and paste the token; you can pick the model, the document language and whether to force OCR.
3. Use it on one document via Parse again → Parse with MinerU in the reader; make it the default under Settings → Capability providers → Document parsing; or let the agent and workflows call Parse a document with MinerU (the result is stored as another parse of that document).

Imports are always parsed locally first; sending a document to MinerU only happens when you name it — the document is uploaded to MinerU. Files are limited to 200 MB and 200 pages, and the free quota caps pages per day. MinerU only serves mainland China; from abroad or behind a global proxy, see the Network setting under Credentials above. Importing and reading documents is covered in Documents.

Manim teaching animations#

Use the Manim plugin when the content must be correct and change step by step (a term moves across, an edge rotates, a line of code lights up). Video generation models give plausible footage, not correct derivations; the Remotion plugin shines at polished text-and-chart cards, while Manim is the better fit for maths, geometry and algorithms.

1. Install “Manim Teaching Animation” from the plugin market, create a connection and grant its permissions.
2. Run “Prepare Manim” once on the plugins page. It creates a Python environment in the plugin's own data directory, installs Manim, checks LaTeX and renders a test frame. The first run takes a few minutes; anything missing comes back with how to install it:
   • Windows: nothing to install.
   • macOS: run brew install cairo pkg-config and xcode-select --install in Terminal.
   • Linux: sudo apt install build-essential pkg-config libcairo2-dev libpango1.0-dev (the matching devel packages with dnf on Fedora).
   • No ffmpeg needed (Manim bundles its encoder). LaTeX is optional: with MiKTeX / MacTeX / TeX Live formulas are typeset; without it explainers show formulas as a line of plain text and still render.
3. Let the agent or a workflow call “Manim explainer”: a title plus each step's title, narration and points, and one visual — formulas, a function plot (sin(x) + x^2/8) or code with lines boxed in turn. Step length follows the narration's reading time; the result lists each step's start and end, and can include an .srt subtitle file.

“Manim custom animation” and “Manim still” run a piece of Python code on this computer, so they are off by default — tick them in the plugin's tool list yourself. By default they may only import drawing modules and may not read or write files or start processes — a guardrail, not a sandbox. See the Manim plugin page.

Create a connection#

Select a plugin and use New connection in its header. Enter configuration in the dialog; configuration, permissions and selected tools belong to that connection. A plugin can have multiple connections. For the Blender workbench, see 3D scenes & animation.