Skip to content
ajan.io

Docs menu

On this page

Building MCP Servers with MCP Apps

MCP Apps is an official MCP extension that lets your server return interactive UIs rendered directly inside ajan and other MCP hosts.

What is MCP Apps?

MCP Apps is an official extension to the Model Context Protocol that lets MCP servers return interactive HTML/JavaScript interfaces — rendered directly in the host application (ajan, Claude Desktop, VS Code, etc.) — instead of plain text.

How It Works

Tool declares a UI resource

Your tool definition includes a _meta.ui.resourceUri pointing to a ui:// resource served by your MCP server. This tells compatible hosts that the tool has a UI component.

Host fetches and renders the UI

When the LLM calls the tool, the host fetches the HTML from your server and renders it in a sandboxed iframe. In ajan, the iframe appears as a standalone output in the chat after the tool call. On desktop, you can open it in the side panel or show it in the chat.

Bidirectional communication

The UI and host communicate via JSON-RPC over postMessage. Your app can request tool calls, update the model's context, and receive results — all without leaving the conversation.

View MCP Apps in Chat

When an MCP tool declares a UI resource, ajan displays the MCP App as a standalone output in the chat after the tool finishes. The app appears outside the tool call details. Standard MCP tools without a UI resource continue to show their regular output.

On desktop, select Open in side panel to move the app to a resizable side panel while you continue the conversation. Select Show in chat to return it to the chat.

Security Model

MCP Apps runs in a sandboxed environment. The host controls what your app can access:

LayerWhat it does
Iframe sandboxIsolates the app from the parent page and other tabs
App HTMLajan renders the HTML returned by your MCP server directly in the sandbox without inspecting or sanitizing it
Enabled resourcesApps can read only resources enabled for the integration
Auditable JSON-RPCAll app-to-host communication is loggable
Confirmation gateApps cannot call tools or read resources that require confirmation

Building Your Own

The official SDK is @modelcontextprotocol/ext-apps. It works with React, Vue, Svelte, Solid, Preact, and vanilla JavaScript.

The core pattern: a tool definition declares _meta.ui.resourceUri, which points to a ui:// resource your server serves as HTML. ajan fetches and renders it in a sandboxed iframe as a standalone output in the chat. On desktop, you can also open it in the side panel.

typescript
import {
  registerAppResource,
  registerAppTool,
  RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";

const resourceUri = "ui://my-form";

registerAppTool(
  server,
  "render_form",
  {
    inputSchema: {},
    _meta: { ui: { resourceUri } },
  },
  async () => ({
    content: [{ type: "text", text: "Opening form..." }],
  }),
);

registerAppResource(
  server,
  resourceUri,
  resourceUri,
  { mimeType: RESOURCE_MIME_TYPE },
  async () => ({
    contents: [
      {
        uri: resourceUri,
        mimeType: RESOURCE_MIME_TYPE,
        text: "<html>...</html>",
      },
    ],
  }),
);

Example: ServiceNow MCP Server

The ajan ServiceNow MCP Server is a reference implementation that shows how to combine OAuth Dynamic Client Registration (DCR) with MCP Apps forms for creating ServiceNow records from within ajan.

It exposes four tools:

ToolDescription
get_form_fieldsRetrieves available fields from a ServiceNow table
render_formReturns an interactive MCP Apps form, optionally pre-filled from conversation context
submit_formCreates a record in ServiceNow from the submitted form data
update_formUpdates fields in an existing ServiceNow form after render_form runs

Connecting to ajan

Once your MCP server is running, connect it to ajan the same way as any MCP server. See the MCP integration guide for setup instructions, including authentication options.