SDK quickstart

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.

This quickstart builds a weather app with the Apps SDK. One file defines three layers:

Server: get_temperature, a data tool with no UI, and show_weather, a render tool.
View: a detail card from the view kit, shown in chat when show_weather runs.
Look pack: the design tokens the card reads.

The SDK sits on the open MCP Apps standard. The app it builds is an ordinary MCP server, so it works in any host that supports MCP Apps. Prefer to write every line yourself? See the same app without the SDK.

This server has no authentication so the example stays short. A server that reads or changes user data must require OAuth. See Authentication.

1. Create the app

npx create-allternit-app weather
cd weather
npm install

The scaffold is five files. server.ts is the whole app.

2. Read the server

server.ts

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

const TEMPS: Record<string, number> = { london: 14, tokyo: 22, austin: 31 };

const card = view({
  uri: "ui://weather/card.html",
  name: "Weather card",
  kit: { tag: "allternit-detail", fields: { title: "city", labels: { temperatureC: "Temperature (°C)" } } },
});

export default defineApp({
  name: "Weather",
  version: "0.1.0",
  description: "Look up the current temperature for a city.",
  tools: [
    appTool({
      name: "get_temperature",
      title: "Get temperature",
      description: "Get the current temperature in Celsius for london, tokyo or austin.",
      input: { city: z.string().describe("City name, e.g. london") },
      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
      handler: async ({ city }) => {
        const t = TEMPS[city.toLowerCase()];
        if (t === undefined) return { isError: true, content: [{ type: "text", text: `Unknown city: ${city}` }] };
        return { content: [{ type: "text", text: `${city}: ${t} °C` }] };
      },
    }),
    appTool({
      name: "show_weather",
      title: "Show weather card",
      description: "Display a weather card for a city. Call only when the user wants to see it.",
      input: { city: z.string() },
      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
      view: card,
      handler: async ({ city }) => {
        const t = TEMPS[city.toLowerCase()];
        if (t === undefined) return { isError: true, content: [{ type: "text", text: `Unknown city: ${city}` }] };
        return {
          content: [{ type: "text", text: `Showing weather for ${city}: ${t} °C` }],
          structuredContent: { city, temperatureC: t },
        };
      },
    }),
  ],
  views: [card],
  lookPack: {
    id: "weather",
    name: "Weather",
    tokens: {
      color: {
        $type: "color",
        surface: { $value: "#ffffff" },
        text: { $value: "#1f1e1d" },
        brand: { $value: "#1f1e1d" },
        "on-brand": { $value: "#ffffff" },
      },
      radius: { card: { $value: "12px" } },
    },
  },
});

Things to notice:

appTool will not build a tool unless you state readOnlyHint and destructiveHint. Permission prompts and directory review depend on them.
view: card ties show_weather to the View. The SDK sets _meta.ui.resourceUri (and the older flat key) for you.
The render tool returns content (text the model reads) and structuredContent (data the View reads).
The View has no network access. view() declares an empty CSP unless you add domains.

3. Run it

npx allternit dev

allternit dev starts the server on port 3000 and prints the MCP URL, the manifest URL and the command to add it as a connector.

4. Test it

npx allternit test

allternit test runs the same rules directory review runs (annotations, descriptions, CSP), then starts the server and checks what a real MCP client sees: the tools, the ui:// resource and its MIME type. It exits non-zero on errors.

5. Make the server reachable and connect it

Allternit connects to your server from its own infrastructure, so the URL must be public and use https. Connector URLs that resolve to loopback, private, or link-local addresses are refused. During development, expose your local port through a tunnel. Then add the server as a connector. This request uses the connector API:

curl -X POST https://api.allternit.com/mcp/connectors \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "Weather",
    "name_id": "weather",
    "url": "https://<your-tunnel-host>/mcp",
    "type": "http"
  }'

If you run your own Allternit API for development, set ALLTERNIT_MCP_ALLOW_PRIVATE_CONNECTORS=1 on it to allow connectors that resolve to a local address.

6. See it render

Start a chat and ask: “Show me the weather in Tokyo.” The model calls show_weather, and the card appears in the conversation, styled by your look pack. If it does not, see Troubleshooting.

7. Package it

npx allternit package --url https://<your-host>/mcp

This writes weather.zip in the layout Package your plugin describes.

Next steps

Learn each package: Overview, Server, Bridge, View kit, Look packs, CLI.
Add OAuth: Authentication.
Submit it: Submit and review.

Concepts

Get Started

Apps SDK

Build

Test & Publish

Guides

Reference

1. Create the app

2. Read the server

3. Run it

4. Test it

5. Make the server reachable and connect it

6. See it render

7. Package it

Next steps

​1. Create the app

​2. Read the server

​3. Run it

​4. Test it

​5. Make the server reachable and connect it

​6. See it render

​7. Package it

​Next steps

1. Create the app

2. Read the server

3. Run it

4. Test it

5. Make the server reachable and connect it

6. See it render

7. Package it

Next steps