apps-server

Preview. The Allternit Apps SDK packages and the allternit CLI are not published to npm yet, so the install commands on this page do not work outside the Allternit repository today. To build an MCP App now, follow the Quickstart, which uses the open MCP SDK directly. Your app will not need changes to adopt the SDK later.

@allternit/apps-server is a thin layer over the official MCP SDK v2 (@modelcontextprotocol/server 2.3.1) and @modelcontextprotocol/ext-apps 2.0.3. It does not hide them: app.createServer() returns a normal McpServer. Every app it builds is dual-era by default: it speaks MCP 2026-07-28 (stateless, server/discover, a _meta envelope on each request) and still answers clients that open with the older initialize handshake. Tools are listed in name order and Views in URI order, so tools/list and resources/list are the same on every request. Tool input shapes are Zod 4 (the z re-exported by the package).

npm install @allternit/apps-server

`defineApp`

import { defineApp } from "@allternit/apps-server";

export default defineApp({
  name: "Weather",              // 30 characters or fewer
  version: "0.1.0",
  description: "…",
  tools: [/* appTool(...) */],
  views: [/* view(...) */],
  lookPack: { /* see Look packs */ },
  permissions: { auth: "none" },   // "none" | "oauth"; optional network, notes
  instructions: "…",               // shown to the model
});

defineApp throws on mistakes you would otherwise find in review: duplicate tool names or View URIs, a tool that points at a View you did not list, a malformed or over-broad CSP domain, an invalid look pack. It returns an app with four members:

Member	What it does
`manifest({ url? })`	The `allternit.app.json` object.
`lint()`	The directory scan rules over the declared tools and Views.
`createServer()`	A new `McpServer` with every tool and View registered.
`input`	What you passed in.

`appTool`

import { appTool, z } from "@allternit/apps-server";

appTool({
  name: "delete_item",
  title: "Delete item",
  description: "Permanently delete an item by id.",
  input: { id: z.string() },
  annotations: { readOnlyHint: false, destructiveHint: true },
  view: "ui://items/confirmation.html", // optional: a view() or its URI
  handler: async ({ id }) => ({ content: [{ type: "text", text: `Deleted ${id}` }] }),
});

readOnlyHint and destructiveHint are required and must be booleans. Stating them is the point: the host decides when to ask the user, and directory review checks them against the tool’s name. A tool cannot be both read-only and destructive. When a tool has a view, the SDK registers it with registerAppTool, which sets _meta.ui.resourceUri and the older flat _meta["ui/resourceUri"] key. z is re-exported from zod so the input shape and your code use one version.

`view`

A View is a ui:// resource. Build it from the view kit or write the HTML yourself.

import { view } from "@allternit/apps-server";

// From the view kit: no HTML to write.
view({
  uri: "ui://items/list.html",
  name: "Items",
  kit: { tag: "allternit-table", path: "items", fields: { columns: ["name", "status"] } },
});

// Hand-written HTML.
view({
  uri: "ui://items/custom.html",
  name: "Custom",
  html: "<!doctype html><html><head></head><body>…</body></html>",
  csp: { connectDomains: ["https://api.example.com"] },
});

Option	Meaning
`uri`	`ui://<app>/<name>.html`
`kit`	`{ tag, path?, fields?, submitTool? }`. `path` is a dot path into the tool result’s `structuredContent`. For a form, `submitTool` is called with the values on submit.
`html`	Your own document. Give exactly one of `kit` or `html`.
`csp`	Domains the View may reach. Default: none. Wildcards and malformed hosts are refused.
`prefersBorder`	Default `true`.
`openaiCompat`	Inline the compatibility shim for a View written for another host. See Porting.
`allternitExt`	Install `window.allternit`. Default `true`.

The app’s look pack is written into every View as CSS variables, so a Views’ colors come from the pack and change when it does. A kit View also runs a small script that speaks the standard bridge: ui/initialize, host theme variables, ui/notifications/tool-result and size changes.

Serve it

import { listen } from "@allternit/apps-server";
import app from "./server.js";

const running = await listen(app, { port: 3000 });
console.log(running.url); // http://localhost:3000/mcp

listen runs streamable HTTP in stateless mode, a fresh server per request, for both protocol eras. It also answers GET /healthz and GET /allternit.app.json. allternit dev calls it for you. Pass onerror to see tool errors (the default logs them to stderr). To deploy somewhere that takes a web-standard fetch handler (Cloudflare Workers, Bun, Deno), use the handler directly:

import app from "./server.js";

export default app.createHandler(); // { fetch, close } — dual-era, stateless

Events (optional)

An app can offer MCP Events so a host subscribes once and your server calls it back when something happens. Add events to defineApp; see the Events page for the full example.

Validating a manifest

import { validateManifest, hasErrors } from "@allternit/apps-server";

hasErrors(validateManifest(app.manifest()));

validateManifest applies the plugin package rules (name length, required annotations, Views that exist) plus the look pack validator. The scan rules are the same code directory review uses: scanInput, lintTools, lintResources.

Concepts

Get Started

Apps SDK

Build

Test & Publish

Guides

Reference

`defineApp`

`appTool`

`view`

Serve it

Events (optional)

Validating a manifest

​defineApp

​appTool

​view

​Serve it

​Events (optional)

​Validating a manifest

`defineApp`

`appTool`

`view`

Serve it

Events (optional)

Validating a manifest