@App

Checked against FrontMCP 1.11.0 on

@App groups related capabilities, the tools, resources and prompts for one area like tickets or billing, together with the providers they use. A @FrontMcp server hosts one or more apps on the same endpoint. Each app keeps its providers to itself, and can have its own auth and defaults.

@App(options)
class MyApp {}

Reference

@App(options)

Apply @App to an empty class, and list the class in @FrontMcp({ apps }).

help-desk.app.ts
import { App } from "@frontmcp/sdk";
import { CloseTicket, SearchTickets } from "./tools";
import { TicketResource } from "./ticket.resource";
import { TriageTicket } from "./triage.prompt";
import { TicketStore } from "./ticket-store";

@App({
  id: "help-desk",
  name: "Help Desk",
  description: "Search, triage and close support tickets",
  tools: [SearchTickets, CloseTicket],
  resources: [TicketResource],
  prompts: [TriageTicket],
  providers: [TicketStore],
})
export class HelpDeskApp {}

See more examples below.

Options

Required:

OptionTypeDescription
namestringA readable name for logs and tooling, like "Help Desk".

Optional:

OptionTypeDescription
idstringA stable identifier. It prefixes names that clash with another app's, and is the URL path of a standalone app. Defaults to name with spaces replaced by -, so set it: short, lowercase, like help-desk.
descriptionstringWhat the app is for. For your own documentation and tooling; FrontMCP doesn't send it to clients.
toolsToolType[]@Tool classes or tool() functions.
resourcesResourceType[]@Resource and @ResourceTemplate classes.
promptsPromptType[]@Prompt classes or prompt() functions.
providersProviderType[]Providers for this app's tools, resources and prompts. Other apps can't see them.
routesHttpRouteType[]Optional; defaults to none. HTTP routes using this app's providers.
pluginsPluginType[]Plugins that hook into this app's requests, such as caching or auditing, and can add tools and providers of their own. See @Plugin.
adaptersAdapterType[]Adapters that generate tools from another source, such as an OpenAPI spec.
authProvidersAuthProviderType[]Credentials this app's tools can ask for with authProviders on @Tool, such as a GitHub token.
authAuthOptionsInputThis app's auth, overriding the server's auth, for an app with its own endpoint (standalone or splitByApp). On the shared endpoint only the server's auth checks callers, so where the app's would go unchecked the server refuses to start: a server with no auth, or in public, static or transparent mode (a static app that accepts all of a static server's tokens is allowed). In local and remote mode it starts, and app grants are checked per call only with incrementalAuth. The same modes as @FrontMcp. See Auth for one app. (Changed in 1.9.2: before, the shared endpoint ignored it, and the app's tools were as open as the server's.)
outputOutputPolicyDefaults for this app's tool results: schemaMode, schemaDescriptionFormat, undeclaredKeys (default "warn" in development, "strip" otherwise) and budget (below). Overrides the server's settings; a tool's own settings override both. allowNonFinite is accepted here but only the server's value is read. See Output policy and overriding server defaults.
ui{ servingMode? }The serving mode of this app's tools that don't set one. Overrides the server's ui.servingMode; a tool's own ui.servingMode overrides both. A value that isn't a serving mode throws a ZodError when the class is decorated. See Defaults for the server and an app. New in 1.9.4.
standaloneboolean | "includeInParent"Serve the app on its own path. Defaults to false. See standalone apps.
agentsAgentType[]Agents: tools backed by their own model and tools. Each is exposed as a tool.
skillsSkillType[]Skills: step-by-step guides for using several tools together, exposed as resources.
jobsJobType[]Jobs: named units of work with typed input and output, for the server's jobs system.
workflowsWorkflowType[]Workflows that run jobs in steps.
channelsChannelType[]Channels that push events to Claude Code sessions. See @Channel.

Changed in 1.10.16: before, tools contributed by an app's plugins and adapters could miss the app's output policy. They now inherit its schema advertisement and undeclared-key settings too.

Standalone apps

By default every app is served on the server's one MCP endpoint. standalone gives an app its own endpoint, under its id:

standaloneOn the main endpointOn /<id>
false (default)YesNo
trueNoYes
"includeInParent"YesYes
main.ts
@App({ id: "billing", name: "Billing", tools: [GetInvoice], standalone: true })
class BillingApp {}

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp, BillingApp],
  http: { port: 3000, entryPath: "/mcp" },
})
export default class Server {}

// http://localhost:3000/mcp          → Help Desk tools only
// http://localhost:3000/mcp/billing  → Billing tools only

The path is relative to http.entryPath: with the default entry path, /, the billing app is at /billing. The Playground has one endpoint and no paths, so standalone apps can't be shown in it. To give every app its own path, use splitByApp: true on @FrontMcp.

Apps from outside your code

App.remote() connects to another MCP server and serves its tools, resources and prompts as an app. App.esm() loads an app from an npm package and runs it in your process. Remote servers and Loading apps from npm document every option, with examples that run against stand-in servers in the Playground.

main.ts
import { App, FrontMcp } from "@frontmcp/sdk";

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [
    HelpDeskApp,
    App.remote("https://status.example.com/mcp", {
      namespace: "status",
      transportOptions: { timeout: 10_000 },
      remoteAuth: { mode: "static", credentials: { type: "bearer", value: process.env.STATUS_TOKEN! } },
    }),
    App.esm("@acme/crm-mcp@^2.0.0", { namespace: "crm" }),
  ],
})
export default class Server {}
OptionApplies toDescription
namespacebothPrefix for the app's tool, resource and prompt names. For App.esm() it defaults to the package name.
name, descriptionbothOverride the name derived from the URL or package, and describe the app. The app's id is the name you set, else the namespace, else the derived name; two apps with one id stop the server from starting, with DuplicateAppIdError. (Changed in 1.9.3: before, the namespace didn't count, and the server started.)
standalonebothAs for @App.
filterbothWhich of the app's tools, resources and prompts to serve, like { exclude: { tools: ["delete_*"] } }. (Changed in 1.9.2: before, it was ignored.)
transportOptionsremotetimeout (default 30000 ms, for tool calls only), fallbackToSSE (true), headers for every request, and retryAttempts and retryDelayMs: a tool call that fails on the network, times out, or gets HTTP 408, 425, 429 or a 5xx other than 501 and 505 is tried again, 3 times in all by default, or retryAttempts + 1. See retries. (Changed in 1.9.2: before, retryAttempts and retryDelayMs were ignored. Changed in 1.9.3: before, only network failures were retried.)
remoteAuthremoteCredentials for the remote server: { mode: "static", credentials: { type: "bearer", value } } sends them on every request. Remote servers has the other modes: forward, mapped (since 1.9.3) and oauth. (Changed in 1.9.2: before, it sent nothing.)
refreshInterval, cacheTTLremoteHow often to re-read the remote server's capabilities (default never), and how long to cache them (default 60000 ms).
autoUpdate, cacheTTL, loader, importMapesmPoll for new versions that match the range; how long to cache a loaded package; a loader that replaces the server's for this app; and an import map, which rewrites the package's imports of the packages it names. (Changed in 1.9.2: before, importMap was ignored.)

Without its own loader, App.esm() fetches packages with the server's loader settings.

app(options)

The function form takes the same options and returns an app class, for code that builds apps from data rather than declaring them. See building an app without a decorator.

Caveats

  • The class body is ignored. Keep it empty.
  • Every entry in tools, resources, prompts and providers must be decorated (or made with the function form). The server fails to start otherwise.
  • An app's providers are private to it. To share one between apps, register it on @FrontMcp({ providers }).
  • When two apps expose a tool with the same name, FrontMCP renames both to <id>:<name>. See when two apps use the same name.

Budgeting answers

output.budget: { maxBytes, lists? } limits the answers of the app's tools and the reads of its resources. It defaults to off. A tool overrides its app, and an app overrides the server; false disables an inherited budget. Resources take the app's budget, else the server's, and UI widget resources are never cut. maxBytes is a whole number of at least 1024; lists is "keep-newest" (default) or "keep-oldest". See the tested tool example. New in 1.11.0.


Usage

Grouping capabilities into an app

Put everything one area needs in one app: its tools, its resources, its prompts, and the providers they share. Open the Capabilities tab to see what the app exposes.

Open
import { App } from "@frontmcp/sdk";
import { SearchTickets } from "./search-tickets.tool";
import { TicketResource } from "./ticket.resource";
import { TriageTicket } from "./triage.prompt";
import { TicketStore } from "./ticket-store";

@App({
  id: "help-desk",
  name: "Help Desk",
  tools: [SearchTickets],
  resources: [TicketResource],
  prompts: [TriageTicket],
  providers: [TicketStore],
})
export class HelpDeskApp {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

Hosting several apps on one server

List each app in @FrontMcp({ apps }). Clients see one server, with every app's tools in one tools/list.

Open
import { FrontMcp } from "@frontmcp/sdk";
import { HelpDeskApp } from "./help-desk.app";
import { BillingApp } from "./billing.app";

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

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

When two apps use the same name

Tool names must be unique on a server. When two apps each have a search tool, FrontMCP keeps both and renames them to <id>:<name>. The model sees the prefixed names. A call to the plain name still works, and reaches the first app in apps without saying so.

Open
import { App, FrontMcp, Tool, ToolContext, z } from "@frontmcp/sdk";

@Tool({ name: "search", description: "Search support tickets", inputSchema: { query: z.string() } })
class SearchTickets extends ToolContext {
  async execute({ query }: { query: string }) {
    return { tickets: [`T-1 (matched "${query}")`] };
  }
}

@Tool({ name: "search", description: "Search invoices", inputSchema: { query: z.string() } })
class SearchInvoices extends ToolContext {
  async execute({ query }: { query: string }) {
    return { invoices: [`INV-7 (matched "${query}")`] };
  }
}

@App({ id: "desk", name: "Help Desk", tools: [SearchTickets] })
class DeskApp {}

@App({ id: "billing", name: "Billing", tools: [SearchInvoices] })
class BillingApp {}

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

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

The renaming only happens on a clash, so adding an app can rename tools that clients already use. Give tools names that are unique across the server, like search_tickets and search_invoices, and the question never comes up.

Keeping providers private to an app

A provider registered on an app is visible to that app only. One registered on @FrontMcp is shared by every app, as a single instance. Here both apps count into the same Metrics, but only the help desk can see TicketStore.

Open
import { App, FrontMcp, Provider, Tool, ToolContext, z } from "@frontmcp/sdk";

@Provider({ name: "Metrics" })
class Metrics {
  calls = 0;
}

@Provider({ name: "TicketStore" })
class TicketStore {
  count = 3;
}

@Tool({ name: "count_tickets", description: "Count open tickets", inputSchema: {} })
class CountTickets extends ToolContext {
  async execute() {
    const calls = ++this.get(Metrics).calls;
    return { open: this.get(TicketStore).count, calls };
  }
}

@Tool({ name: "get_invoice", description: "Get an invoice by id", inputSchema: { id: z.string() } })
class GetInvoice extends ToolContext {
  async execute({ id }: { id: string }) {
    const calls = ++this.get(Metrics).calls;
    return { id, calls, canSeeTickets: this.tryGet(TicketStore) !== undefined };
  }
}

@App({ id: "desk", name: "Help Desk", tools: [CountTickets], providers: [TicketStore] })
class DeskApp {}

@App({ id: "billing", name: "Billing", tools: [GetInvoice] })
class BillingApp {}

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

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

Overriding server defaults for one app

Some settings cascade from the server to its apps to each tool, and the most specific one wins. output is one: here the server hides output schemas, and the help desk app puts them in its tools' descriptions instead.

Open
import { App, FrontMcp, Tool, ToolContext, z } from "@frontmcp/sdk";

@Tool({
  name: "ticket_stats",
  description: "Count open and closed tickets",
  inputSchema: {},
  outputSchema: z.object({ open: z.number(), closed: z.number() }),
})
class TicketStats extends ToolContext {
  async execute() {
    return { open: 12, closed: 40 };
  }
}

@Tool({
  name: "invoice_stats",
  description: "Count paid and unpaid invoices",
  inputSchema: {},
  outputSchema: z.object({ paid: z.number(), unpaid: z.number() }),
})
class InvoiceStats extends ToolContext {
  async execute() {
    return { paid: 30, unpaid: 4 };
  }
}

@App({ id: "desk", name: "Help Desk", tools: [TicketStats], output: { schemaMode: "description" } })
class DeskApp {}

@App({ id: "billing", name: "Billing", tools: [InvoiceStats] })
class BillingApp {}

@FrontMcp({ info: { name: "support", version: "1.0.0" }, apps: [DeskApp, BillingApp], output: { schemaMode: "none" } })
export default class Server {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

schemaMode can be "definition" (the default: send it as outputSchema), "description", "both" or "none". ui.servingMode cascades the same way (since 1.9.4): see Defaults for the server and an app.

Building an app without a decorator

app() builds an app from a plain object. It's useful when the list of tools comes from data, such as a config file or a loop.

Open
import { app, tool } from "@frontmcp/sdk";

const counts = { open: 12, closed: 40, pending: 3 };

const tools = Object.entries(counts).map(([status, count]) =>
  tool({ name: `count_${status}`, description: `How many tickets are ${status}`, inputSchema: {} })(async () => ({ count })),
);

export const helpDesk = app({ id: "help-desk", name: "Help Desk", tools });

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

Lazy apps

An app can declare { id?, name, description?, lazy: () => Promise<unknown>, enabled? } instead of importing its class at startup. Until the first call imports it, the build manifest answers the lists for its tools, resources, resource templates and prompts. Concurrent first calls share that import. New in 1.11.0.

Lazy app fieldTypeDefaultDescription
namestringrequiredThe app's name. Without id, the id is derived from it, as for @App.
idstringderived from nameMust equal the id of the @App the import loads; otherwise the import fails with LAZY_APP_CONFIGURATION_ERROR.
descriptionstringnoneWhat the app provides.
lazy() => Promise<unknown>requiredImports the app: resolves to its @App class, or to a module whose default export, or only @App export, is one.
enabledEnabledOptiononThe same switch as an entry's. While it is off, the app's entries are refused with FEATURE_OFF and the app is never imported.
apps: [{ id: "reports", name: "Reports", lazy: () => import("./reports.app.js") }],
manifest: "./frontmcp.manifest.json",

Ship the manifest next to the server's entry, or pass manifest on @FrontMcp. Without one, a server outside production logs that its lazy apps load at startup, and imports them then; with NODE_ENV=production, startup fails with LAZY_APP_CONFIGURATION_ERROR. An import that fails answers each call LAZY_APP_LOAD_FAILED, with a remedy; one that can be retried is imported again on the next call. When the loaded app's lists differ from the manifest's, the server announces the lists that changed.

A lazy app is listed before its code runs, so nothing in it may need that code to be listed, and it may set up nothing that only startup sets up. The app is refused with LAZY_APP_CONFIGURATION_ERROR, at startup when the manifest shows it or when it's imported, and its calls answer LAZY_APP_LOAD_FAILED until the server restarts, when:

  • the app declares jobs, workflows, channels, skills or agents, its own auth, standalone or ui defaults;
  • it has @Duty providers, a plugin with scope: "server", a hook with appliesTo: "all-apps", or a hook on a flow other than tools/call, resources/read, prompts/get and completion/complete, which runs for every app;
  • one of its tools, resources, templates or prompts declares authorities, a ui widget or an enabled source of its own, or featureFlag or codecall, which those plugins read before the call. Put a featureFlagSource() on the lazy app's enabled instead.

Troubleshooting

tools items must be annotated with @Tool() | @FrontMcpTool(), be a package specifier string, or come from Tool.esm() | Tool.remote().

The server fails to start with @App invalid metadata for "tools", and the index of the bad entry. That entry is a class without @Tool. (Changed in 1.9.1: the message used to end at or be a package specifier string., before Tool.esm() and Tool.remote() entries were accepted.) Check that the decorator is there and that you imported the class, not something else with the same name. The same kind of message appears for resources, prompts and providers.

A tool was renamed to desk:search

Another app on the same server has a tool with the same name, so FrontMCP prefixed both with their app's id. Rename one of the tools. See when two apps use the same name.

Provider "TicketStore" is not available: not found in local or parent registries

The tool's app can't see the provider. Often it's registered on a different app:

Open
import { App, FrontMcp, Provider, Tool, ToolContext, z } from "@frontmcp/sdk";

@Provider({ name: "TicketStore" })
class TicketStore {
  forInvoice(id: string) {
    return ["T-2"];
  }
}

@Tool({ name: "get_invoice", description: "Get an invoice and its tickets", inputSchema: { id: z.string() } })
class GetInvoice extends ToolContext {
  async execute({ id }: { id: string }) {
    return { id, tickets: this.get(TicketStore).forInvoice(id) };
  }
}

// 🚩 TicketStore belongs to the help desk app, so billing can't see it
@App({ id: "desk", name: "Help Desk", providers: [TicketStore] })
class DeskApp {}

@App({ id: "billing", name: "Billing", tools: [GetInvoice] })
class BillingApp {}

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

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

Move the provider to @FrontMcp({ providers }) to share it, or register it in the app that uses it.

A standalone app's tools are missing

With standalone: true, an app is only served at <entryPath>/<id>, not on the main endpoint. Point the client at the app's own URL, or use standalone: "includeInParent" to serve it in both places.

Report a docs issue · Report a security concern privately