ChatGPT Plugins (Apps SDK) Guide: Build an ERP Plugin on MCP

I went back to the Apps SDK documentation to build a small ChatGPT integration for an ERP, a tool that answers where a sales order is, and the URL dropped me on a page titled Plugins. The tutorials I had bookmarked said apps, the ChatGPT settings said plugins, and older answers still said connectors. They are the same product line under three names, and the code underneath barely changed.

This post untangles the names with dates, then builds the thing: a read-only MCP server with one ERP tool, an order-status card rendered as an MCP App, a skill that wraps the tool in a follow-up workflow, local testing, and what the directory submission asks for. Every API name comes from OpenAI's plugin docs or the official ext-apps repository, cited at the end.

Connectors, apps, plugins: one product line, three names

If you searched for ChatGPT plugins Apps SDK and found pages that disagree, it is because the naming moved three times in under a year. None of the moves broke the underlying contract: ChatGPT connects to a remote MCP server and calls its tools.

The practical consequence: an Apps SDK tutorial from late 2025 is still mostly correct about the MCP server, and mostly wrong about packaging and distribution. Keep the server code, re-read everything about where it is published. Also note that these plugins are unrelated to the 2023 plugin beta, which was shut down in April 2024. Same word, different system.

What a ChatGPT plugin actually is in 2026

OpenAI's plugin architecture page lists the parts, and only some are mandatory. Start with the smallest shape that covers the use case; the docs explicitly allow adding an MCP server or UI later.

• An MCP server, which gives the plugin tools and access to external systems. It must speak the streamable HTTP transport at a stable public URL, usually ending in /mcp.
• Skills, which are folders with a SKILL.md file. ChatGPT reads each skill's name and description first and loads the full instructions only when it decides the skill applies.
• An optional UI, a component rendered inside ChatGPT when a specific tool returns. It is built on the open MCP Apps standard rather than a ChatGPT-only format.

erp-order-status/
├── plugin.json          # manifest: name, version, description, OpenAI extensions
├── mcp.json             # where the remote MCP server lives
├── .app.json            # maps the registered MCP app; referenced from plugin.json
└── skills/
    └── late-order-follow-up/
        └── SKILL.md     # the workflow the model follows around the tool

# plugin.json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "erp-order-status",
  "version": "1.0.0",
  "description": "Look up sales order status from the ERP and draft customer updates.",
  "extensions": {
    "com.openai": {
      "apps": "./.app.json",
      "interface": { "displayName": "ERP Order Status", "category": "Productivity" }
    }
  }
}

# mcp.json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "erp-order-status": {
      "type": "streamable-http",
      "url": "https://erp-mcp.example.com/mcp"
    }
  }
}

The manifest is a portable plugin.json at the root, with OpenAI-specific fields under an extensions.com.openai block. That split matters if you also target Codex: OpenAI says one published plugin lands in a directory shared by ChatGPT and Codex, and Codex reads a .codex-plugin/plugin.json fallback.

Building the ERP order-status MCP server

The tool answers one question and nothing else: given a sales order number, return its stage, promised date and line-level shipped quantities. It reads from a read model over the ERP, never from an endpoint that can post a document. The registration below follows the shape of the official ext-apps example, which uses registerAppTool so the tool can carry a link to its UI.

// server.ts
import {
  registerAppResource,
  registerAppTool,
  RESOURCE_MIME_TYPE, // "text/html;profile=mcp-app"
} from "@modelcontextprotocol/ext-apps/server";
import { McpServer } from "@modelcontextprotocol/server";
import fs from "node:fs/promises";
import { z } from "zod";
import { findSalesOrder } from "./erp.js"; // read model over the ERP, never the write API

const ORDER_CARD_URI = "ui://order-status/v1.html";

export function createServer(): McpServer {
  const server = new McpServer({ name: "erp-order-status", version: "1.0.0" });

  registerAppTool(
    server,
    "get_order_status",
    {
      title: "Get sales order status",
      // The description is routing logic: it decides when ChatGPT calls you.
      description:
        "Use this when the user asks where a sales order is: confirmed, picking, " +
        "shipped or invoiced. Read-only. It cannot change, cancel or reprice an order.",
      inputSchema: z.object({
        orderNumber: z.string().regex(/^SO-\d{6}$/).describe("Sales order number, e.g. SO-004217"),
      }),
      outputSchema: z.object({
        orderNumber: z.string(),
        stage: z.enum(["confirmed", "picking", "shipped", "invoiced"]),
        promisedDate: z.string(),
        lines: z.array(z.object({ sku: z.string(), ordered: z.number(), shipped: z.number() })),
      }),
      // Explicit booleans, all three. Reviewers check these against behaviour.
      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
      // Standard MCP Apps key. ChatGPT also reads the alias _meta["openai/outputTemplate"].
      _meta: { ui: { resourceUri: ORDER_CARD_URI } },
    },
    async ({ orderNumber }) => {
      const order = await findSalesOrder(orderNumber);
      if (!order) {
        return { isError: true, content: [{ type: "text", text: `No sales order ${orderNumber}.` }] };
      }
      return {
        // Seen by the model AND the card. Keep it small: it stays in context.
        structuredContent: {
          orderNumber,
          stage: order.stage,
          promisedDate: order.promisedDate,
          lines: order.lines,
        },
        // What the model narrates from.
        content: [{ type: "text", text: `${orderNumber} is ${order.stage}, promised ${order.promisedDate}.` }],
        // Card-only data the model never sees. No trace IDs or internal keys here either.
        _meta: { warehouseLabel: order.warehouseDisplayName },
      };
    },
  );

  registerAppResource(
    server,
    "Order status card",
    ORDER_CARD_URI,
    { mimeType: RESOURCE_MIME_TYPE },
    async () => ({
      contents: [
        {
          uri: ORDER_CARD_URI,
          mimeType: RESOURCE_MIME_TYPE,
          text: await fs.readFile("dist/order-card.html", "utf-8"), // single-file Vite build
          // Empty allowlists: the card fetches nothing. Widen only what you use.
          _meta: { ui: { prefersBorder: true, csp: { connectDomains: [], resourceDomains: [] } } },
        },
      ],
    }),
  );

  return server;
}

The return value has three channels, and they are the easiest part to get wrong. structuredContent is concise data that both the model and the UI read, and it stays available to the model in later turns, so it should hold facts rather than pages of rows. content is the text the model narrates from. _meta is client-specific data hidden from the model, useful for display-only labels.

The description and the annotations do more work than the handler. The description is how ChatGPT decides to call the tool, so it says when to use it and what it cannot do. The three annotations must be explicit booleans: readOnlyHint true for retrieval, destructiveHint false because nothing is overwritten, openWorldHint false because the data is confined to one private ERP tenant.

Returning a UI from the tool with MCP Apps

The UI is an HTML resource with a ui:// URI and the MIME type text/html;profile=mcp-app. The tool points at it through _meta.ui.resourceUri; ChatGPT also accepts the older openai/outputTemplate key as an alias. When the tool runs, the host fetches the resource, renders it in a sandboxed frame and forwards the tool result over postMessage. The App class from the ext-apps package wraps that bridge.

// order-card.ts — bundled into dist/order-card.html
import { App } from "@modelcontextprotocol/ext-apps";

type OrderStatus = {
  orderNumber: string;
  stage: string;
  promisedDate: string;
  lines: { sku: string; ordered: number; shipped: number }[];
};

const app = new App({ name: "Order status card", version: "1.0.0" });
let current: OrderStatus | undefined;

// Wrong: connecting first and attaching handlers afterwards. The initial tool
// result can arrive before anyone is listening, and the card renders empty.
// Right: register every handler, then connect.
app.ontoolresult = (result) => {
  const order = result.structuredContent as OrderStatus | undefined;
  if (order) render(order);
};

document.getElementById("refresh")!.addEventListener("click", async () => {
  if (!current) return;
  // The card can call its own server's tools without a new chat turn.
  const result = await app.callServerTool({
    name: "get_order_status",
    arguments: { orderNumber: current.orderNumber },
  });
  render(result.structuredContent as OrderStatus);
});

function render(order: OrderStatus) {
  current = order;
  // textContent, never innerHTML: structuredContent is untrusted input.
  document.getElementById("stage")!.textContent = order.stage;
  document.getElementById("promised")!.textContent = order.promisedDate;
  const open = order.lines.filter((l) => l.shipped < l.ordered).length;
  document.getElementById("open-lines")!.textContent = String(open);
}

app.connect();

Two rules from the docs shape this code. Treat structuredContent as untrusted input, so the card writes textContent and never innerHTML. And declare a Content Security Policy on the resource: connectDomains for anything the card fetches, resourceDomains for scripts, fonts or images it loads. An order card that only renders the tool result needs neither, so both lists stay empty.

Writing the skill that wraps the tool

A tool says what the ERP can answer; a skill says how a salesperson's task should go. The skill below turns the order-status tool into a late-order follow-up routine. It has the two required fields, a name and a description that tells the model when to consider it, and then plain numbered instructions.

---
name: late-order-follow-up
description: Use when a sales user asks which of a customer's orders are late, or what to tell a customer about a delayed shipment.
---

# Late order follow-up

1. Call get_order_status for every order number the user gives. Never infer a stage.
2. An order is late when its stage is "confirmed" or "picking" and promisedDate is before today.
3. For each late order, list the lines where shipped is less than ordered.
4. Draft a short customer update: what shipped, what has not, and the original promised date.
   Do not promise a new date. The tool does not return one, so any date you write is invented.
5. If the tool returns an error, say the order number was not found and ask the user to check it.
   Do not retry with a "corrected" number you made up.

Most of the value is in the refusals. Step four forbids promising a new delivery date, because the tool never returns one and a confident model will otherwise invent a plausible date for a real customer. Step five stops it retrying with a guessed order number. These are the failure modes I would expect from any model wired to ERP data, and a skill is the cheapest place to close them.

Testing locally and in ChatGPT developer mode

Run the server statelessly: a fresh server and transport per request, no session ID. That is how the ext-apps example is written, and it means any replica behind a load balancer can answer any call. Before ChatGPT sees it, connect the MCP Inspector to the local /mcp endpoint and call the tool by hand with a valid number, an unknown number and a malformed one.

// main.ts
import { createMcpExpressApp } from "@modelcontextprotocol/express";
import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";
import { createServer } from "./server.js";

const app = createMcpExpressApp({ host: "0.0.0.0" });

app.all("/mcp", async (req, res) => {
  const server = createServer();
  const transport = new NodeStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  res.on("close", () => {
    transport.close().catch(() => {});
    server.close().catch(() => {});
  });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(3000);

# then, in another terminal, before ChatGPT ever sees it:
# npx @modelcontextprotocol/inspector    -> connect to http://localhost:3000/mcp

1. Expose the server on a public HTTPS URL. ChatGPT only connects to remote servers that are publicly reachable over HTTPS, so localhost needs a tunnel or a staging deployment.
2. In ChatGPT, open Settings, then Security and login, and turn on developer mode.
3. Under ChatGPT Plugins, select the plus button, enter the MCP server URL and complete the connection details to create a personal plugin.
4. Install it from your personal plugins, then type @ in a chat to invoke it directly and check that the card renders and the narration matches the data.

Getting through Plugin Directory submission

Submission happens in the OpenAI platform dashboard under Plugins, with Upload new or existing plugin. Automated checks run against the package first; you review their findings, add what the review team needs, and submit the draft. Prepare these before you start, because each one blocks the form.

1. Verification and roles: complete individual or business verification for the organisation. Owners can submit; other members need the Apps Management Write role.
2. Listing URLs: an MCP app that needs public review requires all four of websiteURL, supportURL, privacyPolicyURL and termsOfServiceURL.
3. Reviewer access: a dedicated test account, login URL, tenant details and sign-in steps. For an ERP, that means a demo company with realistic orders, never production data.
4. Test cases and a demo: five positive and three negative test cases, plus a video walkthrough reviewers can open.
5. Assets: at minimum an app icon or logo.

Approval does not publish anything. You open the approved version and select Publish plugin when you are ready. The guidelines are where ERP plugins usually need rework: tools must not request the full conversation history or context fields just in case, and responses should not carry session IDs, trace IDs, request IDs or logging metadata. An ERP API returns all of those by default, so map its responses to a narrow shape on purpose.

The name changed three times; the contract did not. Build a narrow, read-only MCP server with honest annotations, return a UI only where a picture beats a sentence, put the workflow and its refusals in a skill, and treat the submission checklist as part of the build rather than paperwork at the end.