Loading apps from npm (ESM)

Checked against FrontMCP 1.12.2 on

App.esm() adds an app whose tools, resources, prompts, skills, agents, jobs, workflows and providers come from an npm package. When the server starts, FrontMCP asks the npm registry which version matches the range you gave, downloads that version as a JavaScript bundle from esm.sh, and runs it in your server's process. The package's tools then sit next to your own, under a namespace. A team can publish tools once and add them to any server without rebuilding it. The flip side is that the package's code runs with your server's permissions, so load only packages you trust.

App.esm(specifier, options?)

Reference

App.esm(specifier, options?)

List the result in @FrontMcp({ apps }), next to your own apps.

main.ts
import { App, FrontMcp } from "@frontmcp/sdk";
import { HelpDeskApp } from "./help-desk.app";

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [
    HelpDeskApp,
    App.esm("@acme/status-tools@^1.0.0", { namespace: "status" }),
  ],
})
export default class Server {}

See more examples below.

Parameters

ParameterTypeDescription
specifierstringA package name, optionally followed by @ and a version: an exact version (1.2.0), a semver range (^1.0.0, ~1.2.0, >=1.0.0 <2.0.0) or a dist-tag (next). Without a version, latest. Names follow npm's rules, lowercase and optionally scoped; anything else, a URL included, makes App.esm() throw Invalid package specifier: "…". See choosing a version.
optionsEsmAppOptionsOptional. See below.

Options

OptionTypeDefaultDescription
namespacestringnamePrefix for every tool, resource and prompt name: status turns get_status into status:get_status. Set it. The default is the package name, which gives names like @acme/status-tools:get_status. Skills, agents, jobs and workflows keep their own names.
namestringThe package nameThe app's name in logs, and the default namespace. The app's id is the name you set, else the namespace, else the package name. Two apps with one id stop the server from starting, with DuplicateAppIdError, so give every App.esm() of one package its own namespace: see choosing a version.
descriptionstringWhat the app is for, for your own tooling.
loaderPackageLoaderThe server's loaderApp settings override the matching server settings; other fields are inherited. Setting either token or tokenEnvVar replaces both server credential fields.
cacheTTLnumber86400000 (24 hours)Milliseconds a downloaded bundle is reused before it's downloaded again. May be 0 to disable bundle reuse. See caching.
autoUpdate{ enabled: boolean; intervalMs?: number }OffCheck the registry every intervalMs (default 300000, 5 minutes) for a newer version in the range, and load it without a restart. See updating without a restart.
standaloneboolean | "includeInParent"falseServe the app on its own path, as for @App. The path is / and the namespace, like /status, unless you set a name, which takes its place. With neither, it's the package name: /@acme/status-tools.
filterAppFilterConfigLoad everythingWhich of the package's tools, resources, prompts, skills, agents, jobs and workflows to load, by their original names. Providers are always loaded. * matches any run of characters. { exclude: { tools: ["delete_*"] } } leaves those out; { default: "exclude", include: { tools: ["get_*"] } } loads only those. An entry left out isn't listed, and calling it gives Tool "…" not found. See loading part of a package.
importMapRecord<string, string>Imports in the bundle to point elsewhere: { "<specifier>": "<target>" }. A key ending in / covers every specifier that starts with it. FrontMCP asks the bundle server to leave those packages out of the bundle, rewrites the bundle's imports, and caches the result apart from a bundle loaded with another map. See rewriting a package's imports.

Returns

A plain object that describes the app, not a class: { name, urlType: "esm", url: specifier, namespace, description, standalone, filter }, with an id taken from namespace when you set one and no name, plus packageConfig: { loader, autoUpdate, cacheTTL, importMap } with the ones you set. Nothing is fetched until the server starts.

The loader

@FrontMcp({ loader }) says where every App.esm() package comes from, unless the app sets its own loader:

main.ts
@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  loader: {
    registryUrl: "https://npm.acme.example",
    url: "https://esm.acme.example",
    tokenEnvVar: "ACME_NPM_TOKEN",
  },
  apps: [App.esm("@acme/internal-tools@^1.0.0", { namespace: "internal" })],
})
export default class Server {}
FieldDefaultWhat it does
urlOne server for both jobs: versions are resolved at <url>/<name> and bundles downloaded from <url>/<name>@<version>?bundle, so it must answer both, as a self-hosted esm.sh in front of a registry would.
registryUrlurl, else https://registry.npmjs.orgWhere versions are resolved. Bundles still come from url, or https://esm.sh without one.
tokenSent as Authorization: Bearer <token> to the registry and the bundle server configured by loader.url. Never sent to the default public esm.sh.
tokenEnvVarThe name of an environment variable that holds the token, read when the package loads. If the variable isn't set, the server doesn't start. When both are set, token wins.

url and registryUrl must be full URLs, like https://npm.acme.example; the server doesn't start otherwise (Invalid URL). See using a private registry.

How a package is loaded

When the server starts, for each App.esm() app, FrontMCP:

  1. Resolves the version. It sends GET <registry>/<name> (the / of a scoped name as %2f) and picks one version from the answer: for latest or another dist-tag, the version the tag points to; for a range, the highest published version that satisfies it. An unknown dist-tag fails startup and names the available tags. It gives up after 15 seconds.
  2. Checks its cache for that exact name@version. See caching.
  3. Downloads the bundle on a miss: GET <bundles>/<name>@<version>?bundle, from esm.sh unless the loader says otherwise, with &external=<packages> for the packages in importMap. It gives up after 30 seconds. Neither time limit can be changed.
  4. Runs the bundle with a dynamic import(). A CommonJS bundle (module.exports = …) works too.
  5. Reads the package's exports (see what a package exports) and registers its entries and providers in the app. Tools, resources and prompts are namespaced; skills, agents, jobs and workflows keep their own names. filter can leave entries out, but providers are always loaded.

If any step fails, the server doesn't start, with one of the errors below. The registry is asked on every start, even when the bundle is cached, so a server that loads packages can't start while the registry is unreachable.

What a package exports

FrontMCP looks for, in this order:

  1. A default export with string name and version fields: a manifest, { name, version, description?, tools?, resources?, prompts?, skills?, agents?, jobs?, workflows?, providers? }. It's the clearest form.
  2. A default export that's an object of entry arrays, an object of decorated entry or provider classes, or one such class.
  3. Named exports, the same three ways: export const name, version and tools; export const tools = […] alone; or exported decorated classes.

Default-exported @App and @FrontMcp classes work too. Anything else stops the server with Invalid manifest in ESM package "…": ESM module does not export a valid FrontMcpPackageManifest.

A tool, resource or prompt can be a decorated class, which works like one in your own code, or a plain object:

EntryFieldsNotes
Toolname, execute(input), and optionally description, inputSchema (a JSON Schema object)execute() can return a CallToolResult, { content: [...] }, which is sent as it is. A string comes back as text; a plain object becomes JSON text and structured content. Arguments are checked against inputSchema when supplied. Without a description, the model sees ESM tool: <name>.
Resourcename, uri, read(), and optionally description, mimeTyperead() returns a ReadResourceResult, { contents: [...] }. The URI isn't namespaced. Without a description: ESM resource: <name>.
Promptname, execute(args), and optionally description, argumentsexecute() returns a GetPromptResult, { messages: [...] }. Required arguments are checked before it runs. Without a description: ESM prompt: <name>.

An entry without a name or without its function, or a resource whose uri has no scheme, is skipped without a word. A manifest can also list skills, agents, jobs, workflows and providers; all are loaded. Providers belong to that version of the package and serve its entries. GLOBAL provider lifecycle hooks run on bootstrap, ready and shutdown. Plain tools receive execute(input, context), resources read(uri, params, context) and prompts execute(args, context), where context.get(Token) resolves package and server providers. Jobs turn on the job system unless jobs.enabled: false.

Caching

In Node, FrontMCP keeps each downloaded bundle in memory and on disk, one folder per name@version holding the bundle and a meta.json. The folder is node_modules/.cache/frontmcp-esm/ in the working directory when it has a node_modules folder, and ~/.frontmcp/esm-cache/ otherwise. A later start with the same version reads the bundle from disk instead of downloading it, until it's cacheTTL old. In a browser, the cache is memory only, so each start downloads again.

The cache key is only name@version: a bundle cached from one loader is reused when another loader resolves the same version. The version itself is always resolved with the registry, as above.

Changed in 1.11.3: before, an app loader replaced the server's settings, bundle downloads received no registry token, and bundle errors always named esm.sh. App settings now merge with the server's, downloads from loader.url receive the token, and errors name the configured server. Downloads from the default public esm.sh still receive no token.

Updating without a restart

With autoUpdate: { enabled: true }, FrontMCP asks the registry every intervalMs which version the range resolves to now. When it's newer than the loaded one, FrontMCP downloads it and swaps the app's tools, resources and prompts for the new version's: tools that the new version dropped disappear, new ones appear, and calls reach the new code. A version outside the range, like 2.0.0 for ^1.0.0, is never loaded. Clients connected with a session, over the protocol versions before 2026-07-28, get notifications/tools/list_changed; 2026-07-28 clients see the change the next time they list.

A failed check is logged and tried again at the next interval. A failed download is logged too, and the old version keeps serving, and the same failed version is retried at the next interval.

main.ts
App.esm("@acme/status-tools@^1.0.0", {
  namespace: "status",
  autoUpdate: { enabled: true, intervalMs: 10 * 60_000 },
})

This was checked in Node against a stand-in registry: publishing 1.1.0 replaced 1.0.0's tools within one interval, and publishing 2.0.0 changed nothing. The examples on this page don't use it, because the check keeps running for as long as the server does.

Replaced versions keep their providers until server shutdown, so calls already running can finish. Each update log counts the retained versions; choose intervalMs with that memory growth in mind. Skills, agents, jobs and workflows are replaced too, and invalid updates leave the loaded version serving.

A package's workers and duties are handed over. Changed in 1.12.0: before, the replaced version's kept running until shutdown, so a "process" worker ran in both versions, and the new version's leased worker or duty failed with a name conflict while the old one kept running. A replace now goes in this order:

  1. The served version's workers and duties stop: each run's signal is aborted, the run is awaited, and its lease, its name and its /readyz check are released. Their own onShutdown() does not run yet: it runs once, when the server shuts down.
  2. The new version's providers get their onReady(), which starts its workers and duties.
  3. The new version's tools, resources and prompts are swapped in.

The replace waits for each run() up to lifecycle.shutdownHookTimeoutMs, 3000 ms by default. A run() that has not ended by then fails the replace, with Provider "<Class>" did not stop its background work within <ms> ms in the log: the new version is discarded, the old one keeps serving, and that worker or duty starts again once its run() has ended, so two runs of it never overlap. The next version check tries the replace again. A new version whose provider throws in onReady(), or whose worker or duty cannot start, as when two of its classes share a name, is discarded the same way, and the old version's workers and duties start again. Changed in 1.12.0: before, such a version was logged and served anyway. A lease store that cannot be opened does not fail the replace: it is retried, and /readyz shows the duty or worker unhealthy meanwhile. This order was read in FrontMCP's source and its tests, not run against a registry.

Running someone else's code

A package loaded with App.esm() is code running inside your server. In Node it can read your environment variables, including secrets, open files and make network requests, with your server's permissions. So:

  • Load only packages you trust, from publishers you trust. The code FrontMCP runs is esm.sh's build of the package, not the tarball on npm, so you're trusting esm.sh too, or whoever serves your loader.url.
  • Pin exact versions for code you don't control. With a range, a new release is loaded at the next restart, without a review or a deploy on your side. With autoUpdate, it's loaded without a restart either.
  • FrontMCP doesn't check the bundle against the registry's integrity hash, or at all.
  • A private registry or mirror, with loader, lets you decide which versions exist.

Errors

A package that can't be loaded stops the server with one of these classes, all exported by @frontmcp/sdk. Each keeps the cause's message after its own, and the cause itself in originalError (except the manifest and specifier errors).

ClasscodeWhenMessage
EsmInvalidSpecifierErrorESM_INVALID_SPECIFIERThe specifier isn't a package name. Thrown by App.esm() itself.Invalid package specifier: "…"
EsmRegistryAuthErrorESM_REGISTRY_AUTH_ERRORThe registry answered 401 or 403.Authentication failed for npm registry: Registry returned 401 for "…"
EsmVersionResolutionErrorESM_VERSION_RESOLUTION_ERRORAny other failure while resolving the version: an unknown package, an unreachable registry, a range nothing satisfies, an unset tokenEnvVar.Failed to resolve version for "<name>@<range>": <cause>
EsmPackageLoadErrorESM_PACKAGE_LOAD_ERRORThe bundle couldn't be downloaded or run.Failed to load ESM package "<name>"@<version>: <cause>
EsmManifestInvalidErrorESM_MANIFEST_INVALIDThe bundle ran, but exports nothing FrontMCP can use.Invalid manifest in ESM package "…": ESM module does not export a valid FrontMcpPackageManifest. …
EsmCacheErrorESM_CACHE_ERRORA cached bundle couldn't be read or written.ESM cache <operation> failed for "…": <cause>

When a package can't be loaded and using a private registry show all but the cache error. Tool.esm() and the other single-entry loaders wrap them in ExternalEntryLoadError.

Caveats

  • Every package loads at startup. If one can't be loaded, the server doesn't start: createFetchHandler() rejects with the loader's error, as createDirect() does. On an edge runtime, like Cloudflare Workers, the server starts on the first request instead. Until it starts, every request gets 503 {"error":"server_unavailable","code":"SERVER_START_FAILED"} with a Retry-After header, and FrontMCP tries again only after that delay, which grows from a second to a minute. Changed in 1.8.4: before, createFetchHandler() always waited for the first request. Changed in 1.8.5: on an edge runtime, that request used to throw, and the next one tried again at once.
  • ESM apps load tools, resources, prompts, skills, agents, jobs, workflows and providers. Package providers belong to the loaded version and stay alive until shutdown when that version is replaced, except that its workers and duties stop at the replace.
  • To load one tool, resource or prompt instead of the whole package, use Tool.esm(), Resource.esm() or Prompt.esm() in an app's lists. Agent.esm(), Skill.esm() and Job.esm() stop the server from starting.

Usage

Loading a package

packages.ts publishes three versions of @acme/status-tools. The server asks for ^1.0.0, so FrontMCP resolves it to 1.2.0, the highest 1.x, downloads that version's bundle, and lists its tool under the status namespace.

Open
import "./npm.example";
import "./packages";
import { App, FrontMcp } from "@frontmcp/sdk";

@FrontMcp({
  info: { name: "support", version: "1.0.0" },
  apps: [App.esm("@acme/status-tools@^1.0.0", { namespace: "status" })],
})
export default class Server {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

The call works like a call to any of your tools; the model sees status:get_status and doesn't know where it came from. In Node, the test usually finds only the registry request: the Playground's first start already put 1.2.0 in the disk cache.

Choosing a version

The part after the last @ picks the version. Here the same package is loaded four times, with four specifiers, each under its own namespace; 2.0.0-beta.1 is published under the next dist-tag:

Open
import "./npm.example";
import "./packages";
import { App, FrontMcp } from "@frontmcp/sdk";

@FrontMcp({
  info: { name: "support", version: "1.0.0" },
  apps: [
    App.esm("@acme/deploy-tools@^1.0.0", { namespace: "stable" }), // the highest 1.x
    App.esm("@acme/deploy-tools@1.0.0", { namespace: "pinned" }),  // exactly 1.0.0
    App.esm("@acme/deploy-tools@next", { namespace: "beta" }),     // the "next" dist-tag
    App.esm("@acme/deploy-tools", { namespace: "latest" }),        // the "latest" dist-tag
  ],
})
export default class Server {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

Each app takes its id from its namespace. Without them, the four apps would share one id, made from the package name, and the server doesn't start, with DuplicateAppIdError, as the last test shows. Give every App.esm() of the same package a namespace of its own. (Changed in 1.9.3: before, an app without a name took its id from the package name, even with a namespace, and the server started; tools/list then left out some of their tools, different ones from start to start.)

A range never picks a prerelease like 2.0.0-beta.1; a dist-tag or an exact version does. An unknown dist-tag refuses startup. Changed in 1.11.3: before, an unknown tag selected the highest version, including prereleases. The version is resolved again at every start, so with a range, the next release is loaded at the next restart. Pin an exact version when that matters, or check for updates while running.

Writing a package FrontMCP can load

A package that FrontMCP can load exports a manifest: its name and version, and arrays of tools, resources and prompts. Plain objects need no dependency on FrontMCP. Publish the package the way you publish any other; FrontMCP loads it through esm.sh, as an ES module or CommonJS.

Export forms

Example 1 of 2

Default export

Open
import { publish } from "./npm.example";

// The package's src/index.js, as esm.sh serves it
publish("@acme/incident-tools", "1.0.0", `
const incidents = [
  { id: "INC-7", service: "api", title: "Elevated error rate" },
  { id: "INC-8", service: "billing", title: "Invoices delayed" },
];

export default {
  name: "@acme/incident-tools",
  version: "1.0.0",
  tools: [
    {
      name: "open_incidents",
      description: "List open incidents, optionally for one service",
      inputSchema: { type: "object", properties: { service: { type: "string" } } },
      execute: async ({ service }) => {
        const open = incidents.filter((i) => !service || i.service === service);
        return { content: [{ type: "text", text: JSON.stringify(open) }] };
      },
    },
  ],
  resources: [
    {
      name: "incidents",
      uri: "incidents://open",
      mimeType: "application/json",
      read: async () => ({
        contents: [{ uri: "incidents://open", mimeType: "application/json", text: JSON.stringify(incidents) }],
      }),
    },
  ],
  prompts: [
    {
      name: "incident_summary",
      description: "Summarize the open incidents for a status page",
      arguments: [{ name: "audience", description: "Who will read it", required: true }],
      execute: async ({ audience }) => ({
        messages: [{ role: "user", content: { type: "text", text: "Read incidents://open and summarize it for " + audience + "." } }],
      }),
    },
  ],
};
`);

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

Link to this example

A package can also export @Tool, @Resource and @Prompt classes, in a manifest's arrays or as exports of their own. FrontMCP registers them like the classes in your own apps, with their input validated and their results shaped as usual. That was checked in Node, with the bundle importing the server's own @frontmcp/sdk; a Playground bundle can't import the Playground's @frontmcp/sdk, so the examples here use plain objects.

Using a private registry

Point loader at your registry and give it a token. Prefer tokenEnvVar, which names an environment variable, over token, so the token stays out of your code. Here the registry is npm.acme.example and the bundles come from esm.acme.example, a self-hosted esm.sh:

Open
import "./npm.example";
import { App, FrontMcp } from "@frontmcp/sdk";

@FrontMcp({
  info: { name: "support", version: "1.0.0" },
  loader: {
    registryUrl: "https://npm.acme.example",
    url: "https://esm.acme.example",
    tokenEnvVar: "ACME_NPM_TOKEN",
  },
  apps: [App.esm("@acme/internal-tools@^1.0.0", { namespace: "internal", cacheTTL: 0 })],
})
export default class Server {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

The token goes to both the registry and the bundle server configured by loader.url; it never goes to the default public esm.sh. A private package needs a bundle server that can build it, such as a self-hosted esm.sh. App-level loader fields override the matching server fields and inherit the rest.

This example sets cacheTTL: 0 so the tests check a bundle download every time. By default, a Node server keeps bundles on disk between starts, while the Playground caches them only in memory. A cached bundle needs no download; the registry still receives a request on every start.

Loading part of a package

filter picks which of a package's tools, resources and prompts the server loads. Patterns match the names the package gives them, before the namespace, and * matches any run of characters. Here the server takes the status tools of @acme/status-admin, but not the one that deletes incidents:

Open
import "./npm.example";
import "./packages";
import { App, FrontMcp } from "@frontmcp/sdk";

@FrontMcp({
  info: { name: "support", version: "1.0.0" },
  apps: [
    App.esm("@acme/status-admin@1.0.0", {
      namespace: "status",
      filter: { exclude: { tools: ["delete_*"] } },
    }),
  ],
})
export default class Server {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

To load only what you list, start from nothing: filter: { default: "exclude", include: { tools: ["get_*"] } }. include and exclude take tools, resources and prompts, each a list of patterns.

Rewriting a package's imports

A bundle can import packages that its bundle server can't build in, like a private dependency, or that your server should provide. importMap names them: FrontMCP asks for the bundle without them (&external=…), and rewrites the bundle's imports to the targets you give. A target is anything import() accepts where the server runs. Here @acme/greeter imports @acme/greetings, and the server supplies it as a data: module:

Open
import "./npm.example";
import "./packages";
import { App, FrontMcp } from "@frontmcp/sdk";

const greetings = "export const greet = (name) => 'Hello, ' + name + '!';";

@FrontMcp({
  info: { name: "support", version: "1.0.0" },
  apps: [
    App.esm("@acme/greeter@1.0.0", {
      namespace: "greet",
      importMap: { "@acme/greetings": `data:text/javascript,${encodeURIComponent(greetings)}` },
    }),
  ],
})
export default class Server {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

A key ending in /, like "@acme/util/", rewrites every import that starts with it, keeping the rest of the path. The rewritten bundle is cached under its own key, so changing the map downloads the bundle again.

Loading one tool from a package

Tool.esm(specifier, name) loads a single tool from a package into one of your apps, next to your own tools. It keeps its own name, with no namespace, and the package's other tools aren't loaded. Resource.esm() and Prompt.esm() do the same for a resource or a prompt. A package specifier string in an app's tools, like tools: ["@acme/status-admin@1.0.0"], loads every tool of the package, also without a namespace. Both load when the server starts, like App.esm(). Since FrontMCP 1.9.1; before, every list rejected what Tool.esm() returns, and a specifier string listed a placeholder that couldn't be called.

Open
import "./npm.example";
import "./packages";
import { App, FrontMcp, Tool, ToolContext } from "@frontmcp/sdk";

@Tool({ name: "ping", description: "Check the server is up", inputSchema: {} })
class Ping extends ToolContext {
  async execute() {
    return { ok: true };
  }
}

@App({ id: "support", name: "Support", tools: [Ping, Tool.esm("@acme/status-admin@1.0.0", "get_status")] })
class SupportApp {}

@FrontMcp({ info: { name: "support", version: "1.0.0" }, apps: [SupportApp] })
export default class Server {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

Tool.esm() takes loader, cacheTTL and metadata; entries from the same package and options share one download. Agent.esm(), Skill.esm() and Job.esm() stop startup with ExternalEntryNotSupportedError; load their entries through App.esm() instead. A package that can't be loaded stops the server with ExternalEntryLoadError, whose message ends with the loader's own, below.

When a package can't be loaded

The server doesn't start, and the error says what failed: createFetchHandler() rejects with it. Its class tells the step apart, and its message ends with the cause, which originalError holds too. Each test here starts a server of its own with a package that can't load:

Open
import { test, expect } from "@frontmcp/testing";
import {
  App,
  EsmInvalidSpecifierError,
  EsmManifestInvalidError,
  EsmPackageLoadError,
  EsmVersionResolutionError,
  FrontMcpInstance,
} from "@frontmcp/sdk";
import "./npm.example";
import { publish } from "./npm.example";

publish("@acme/uptime-tools", "1.0.0", "export default { name: '@acme/uptime-tools', version: '1.0.0', tools: [] };");
publish("@acme/uptime-tools", "1.2.0", "export default { name: '@acme/uptime-tools', version: '1.2.0', tools: [] };");
publish("@acme/half-published", "1.0.0"); // in the registry, but esm.sh can't serve it
publish("@acme/not-a-manifest", "1.0.0", "export const hello = 'world';");

/** Starts a server with one ESM app. It rejects when the package can't be loaded. */
async function start(app: unknown) {
  await FrontMcpInstance.createFetchHandler({ info: { name: "support", version: "1.0.0" }, apps: [app] } as any);
}

/** The error a server with this app fails to start with. */
const failure = (app: unknown) => start(app).then(() => undefined, (e) => e);

test("a package the registry doesn't know", async () => {
  const error = await failure(App.esm("@acme/stauts-tools@^1.0.0"));
  expect(error).toBeInstanceOf(EsmVersionResolutionError);
  expect(error.message).toBe(
    'Failed to resolve version for "@acme/stauts-tools@^1.0.0": Package "@acme/stauts-tools" not found in registry at https://registry.npmjs.org',
  );
});

test("a registry that can't be reached", async () => {
  const error = await failure(App.esm("@acme/uptime-tools@^1.0.0", { loader: { registryUrl: "https://npm.down.example" } }));
  expect(error).toBeInstanceOf(EsmVersionResolutionError);
  expect(error.originalError.message).toBe('Failed to fetch package info for "@acme/uptime-tools": fetch failed');
});

test("a range no published version satisfies", async () => {
  const error = await failure(App.esm("@acme/uptime-tools@^3.0.0"));
  expect(error).toBeInstanceOf(EsmVersionResolutionError);
  expect(error.originalError.message).toBe('No version of "@acme/uptime-tools" satisfies range "^3.0.0". Available versions: 1.0.0, 1.2.0');
});

test("a version esm.sh can't serve", async () => {
  const error = await failure(App.esm("@acme/half-published@1.0.0"));
  expect(error).toBeInstanceOf(EsmPackageLoadError);
  expect(error.message).toBe('Failed to load ESM package "@acme/half-published"@1.0.0: https://esm.sh returned 404 for "@acme/half-published@1.0.0": Not Found');
});

test("a module without a manifest", async () => {
  const error = await failure(App.esm("@acme/not-a-manifest@1.0.0"));
  expect(error).toBeInstanceOf(EsmManifestInvalidError);
  expect(error.message).toContain('Invalid manifest in ESM package "@acme/not-a-manifest": ESM module does not export a valid FrontMcpPackageManifest.');
});

test("a token variable that isn't set", async () => {
  const error = await failure(App.esm("@acme/uptime-tools@^1.0.0", { loader: { tokenEnvVar: "ACME_TOKEN_NOT_SET" } }));
  expect(error).toBeInstanceOf(EsmVersionResolutionError);
  expect(error.originalError.message).toBe('Environment variable "ACME_TOKEN_NOT_SET" is not set. Required for private npm registry authentication.');
});

test("a malformed specifier throws before the server exists", () => {
  expect(() => App.esm("Acme/Status-Tools")).toThrow(EsmInvalidSpecifierError);
  expect(() => App.esm("Acme/Status-Tools")).toThrow('Invalid package specifier: "Acme/Status-Tools"');
});

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

What each one means, and what to do, is under Troubleshooting.


Troubleshooting

Failed to resolve version for "…": Package "…" not found in registry at …

The registry answered 404 for the name. Check the spelling and the scope. For a private package, check that registryUrl points at the registry that has it: without one, FrontMCP asks https://registry.npmjs.org.

Failed to resolve version for "…": Failed to fetch package info for "…": fetch failed

FrontMCP couldn't reach the registry at all: it's down, the host is wrong, or the network doesn't let the server out. FrontMCP asks the registry at every start, so this stops the server even when the bundle is in the cache. The text after the colon is the runtime's own error, like Failed to fetch in browsers.

Failed to resolve version for "…": Timeout resolving version for "…" after 15000ms

The registry didn't answer within 15 seconds. The bundle download has its own limit, 30 seconds: Failed to load ESM package "…"@…: Timeout fetching ESM bundle for "…@…" after 30000ms. Neither can be changed. (Checked in Node against a stand-in that never answers.)

Failed to resolve version for "…": No version of "…" satisfies range "…"

The package exists, but no published version is in the range. The message lists up to five published versions. Widen the range, publish a matching version, or use a dist-tag. A range never matches a prerelease; use its exact version or its dist-tag.

Failed to load ESM package "…"@…: https://esm.sh returned 404 for "…@…": Not Found

The registry has the version, but the bundle URL answered 404, or another status. Check that the bundle server can reach the package, and that loader.url points at a server that serves bundles. The message names the configured bundle server. With url set and no registryUrl, both requests go to url, so a plain npm registry there resolves versions and then fails here.

Invalid manifest in ESM package "…": ESM module does not export a valid FrontMcpPackageManifest

The bundle loaded, but FrontMCP found nothing it could use in its exports: no name and version, no tools, resources or prompts array, and no decorated classes. A default-exported @App or @FrontMcp class is also accepted. Export a manifest, as in writing a package.

If the server starts but some tools are missing, those entries were skipped, or filter left them out: every plain-object tool needs a name and an execute function, every resource a name, a uri with a scheme and a read function.

Failed to resolve version for "…": Environment variable "…" is not set. Required for private npm registry authentication.

tokenEnvVar names a variable that isn't set in the server's environment. Set it where the server runs; FrontMCP reads it when the package loads.

Authentication failed for npm registry: Registry returned 401 for "…"

The registry refused the token, or got none (401 or 403). Check the token and its access to the package. FrontMCP sends it as Authorization: Bearer <token> to the registry and a bundle server configured by loader.url, never to the default public esm.sh; app settings inherit the server's token unless they override it. Other statuses fail the version step as Failed to resolve version for "…": Registry returned <status> for "…": <status text>.

Invalid package specifier: "…"

App.esm() throws this as soon as it's called, so the server module doesn't load. The specifier must be an npm package name, lowercase, optionally scoped, optionally followed by @ and a version. URLs aren't accepted. An empty string gives Package specifier cannot be empty.

Tool names start with @acme/status-tools:

That's the default namespace, the package name. Set namespace (or name) in the options: App.esm("@acme/status-tools@^1.0.0", { namespace: "status" }).

A tool's result is the text [object Object]

Changed in 1.11.3: before, plain-object tool outputs were converted with String(value). They now become JSON text and structured content.

A plain-object tool can return data directly for JSON text and structured content, or a complete { content: [...] } result to control the blocks:

Open
import { publish } from "./npm.example";

publish("@acme/status-counts", "1.0.0", `
export default {
  name: "@acme/status-counts",
  version: "1.0.0",
  tools: [
    {
      name: "counts_raw",
      description: "Count open incidents",
      // A plain object becomes JSON.
      execute: async () => ({ open: 2, resolved: 14 }),
    },
    {
      name: "counts",
      description: "Count open incidents",
      // ✅ A CallToolResult
      execute: async () => ({ content: [{ type: "text", text: JSON.stringify({ open: 2, resolved: 14 }) }] }),
    },
  ],
};
`);

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

A string is fine too: it arrives as the text. A decorated @Tool class in a package returns values the usual way.

Report a docs issue · Report a security concern privately