Claude and ChatGPT apps
A web app can be a Claude connector or a ChatGPT app: its actions become tools on an MCP server at the app's own address, people sign in with their accounts in the app, and the tools run as them. A tool's answer can show in the chat as a widget.
Start from a recipe
Two recipes start you off: Claude connector and ChatGPT app. Each is the web starter's sign-in and accounts with one placeholder model, item, two tools (List items and Add an item), a widget, and a /connect page with the steps for its client. They differ only where the client does. The server works with both clients either way.
ib-apps create "Items" --recipe claude-connector
# or: ib-apps create "Items" --recipe chatgpt-appRename item to what the app is about, give it your fields, and add tools. Any web app with the starter's accounts can do the same without a recipe.
Turning the server on
mcp in settings.ib.ts turns on the server at <app address>/mcp, on every environment and on custom domains, with sign-in at the same address. Without it, those paths are the app's own.
export const settings: AppSettings = {
type: "ib/settings/v1",
platform: "web",
// Claude and ChatGPT show the name and description; the consent page names the app.
mcp: { name: "Items", description: "The items your account keeps: list them and add new ones." },
};Tools
A tool is an action that exports mcp beside options. Its name is <model>_<action> (item_create) or a global action's own name (listItems). Its input is exactly the action's declared params, with id added for an action that works on a record. Nothing else is exposed: no record reads or writes of their own, and no builder tools.
export const run: ActionRun = async ({ params, record, caller }) => {
if (!caller?.accountId) throw new Error("Sign in to an account first.");
record.title = String(params.title).trim();
record.account = caller.accountId; // from who's signed in, never from params
record.createdBy = caller.userId ?? null;
await save(record);
};
// The tool's input: exactly these.
export const params: ActionParams = {
title: { type: "string", required: true, description: "A short title." },
notes: { type: "string", description: "Anything else worth keeping with it." },
};
export const options: ActionOptions = { actionType: "create" };
export const mcp: ActionMcp = {
title: "Add an item",
description: "Adds an item to the user's list, shared with the rest of their account.",
destructive: false, // it only adds, so the client needn't ask first
widget: "items", // widgets/items.html shows the answer
};| mcp | |
|---|---|
title | The tool's name in the client's list, at most 60 characters. |
description | What it does and changes, for the person and the model, at most 1,000 characters. Don't name other tools: the directories check. |
readOnly | It changes nothing. A sign-in that only allows reading sees only these. |
destructive | It deletes, overwrites, sends something or spends money, so clients ask before each call. True for a write unless set false. |
idempotent | Running it again with the same input changes nothing more. |
openWorld | It reaches outside the app: email, payments, another API. |
widget | The widget that shows its answers: widgets/<name>.html. |
A read tool is a global action with returnType: true and readOnly: true. Its return value goes to the model as text, so return only what the person needs.
Who a tool runs as
Every call runs as the signed-in person, held to their roles in accessControl/permissions.ib.ts exactly as the app's pages are: signed-in, the user record's own roles, and account-member or account-admin in the account they act in. The action gets them as caller, with userId and accountId. Someone whose roles can't run an action doesn't see its tool.
Take the account and the user from caller, never from params, and give a tool that changes a record a filter on the account in permissions.ib.ts. The model writes the params.
Widgets
A widget is one self-contained HTML page, widgets/<name>.html (inline script and style, at most 512 KB), that the client shows in a sandboxed frame under the tool's answer. It follows MCP Apps, the standard Claude and ChatGPT both render: it gets each answer as structuredContent ({ result } from a global action, { record } from a model action) and can call the app's tools back through the client, as the same person. It makes no requests of its own, so whatever it shows goes in the tool's answer.
// In widgets/items.html: JSON-RPC over postMessage with the client.
const result = await request("ui/initialize", { appInfo: { name: "Items", version: "1.0.0" }, appCapabilities: {} });
notify("ui/notifications/initialized", {});
window.addEventListener("message", (e) => {
if (e.data?.method === "ui/notifications/tool-result") render(e.data.params.structuredContent);
});
// A button in the widget calls a tool back, as the same user.
await request("tools/call", { name: "item_create", arguments: { params: { title } } });The recipes' widgets/items.html is a working one to build on: theming from the client's CSS variables, resizing to fit, and ChatGPT's older window.openai as a fallback. A tool without widget answers as text.
How people sign in
They add the app's address
In Claude, Settings → Connectors → Add custom connector. In ChatGPT, Settings → Apps with Developer mode while the app isn't in its directory. The client finds the rest from the address.
They sign in to the app
The app is the sign-in server for its own address. Someone not signed in goes to the app's /sign-in and comes back once they are: the starter's afterSignIn() does that.
They allow it
A page in the app's name says which client is asking, which account it acts as, and the tools it can use. Allow, and the client gets an hour's token that it refreshes for 30 days of use.
Only Claude's and ChatGPT's callbacks, and loopback addresses for local clients such as Claude Code, can receive a sign-in.
Trying it
Development has its own address, so ib-apps dev is enough: create an account in the app, then add <development address>/mcp to the client. Widgets show in Claude and ChatGPT on the web and desktop. For a quick look at the tools, Claude Code works too: claude mcp add --transport http items <address>/mcp, then /mcp to sign in. Sign-ins are per environment, so production's are production's users.
Logs and sign-outs
Each call is an mcp event in Logs, under the person as appuser:<user record>, with the action's own run under it. Each person may make 60 calls a minute, and runs count as action time. Settings → MCP on the app lists its tools and every signed-in client, with Sign out for owners and admins.
Listing it
Put production on its own domain first. Claude's connector directory takes the production /mcp address with OAuth sign-in, a privacy policy and a support address of your own, and checks each tool's title, description and hints and that every param has a type. OpenAI's app directory asks for the same from an organization verified as your business, plus test prompts, a reviewer account without two-factor sign-in, and a domain check at /.well-known/openai-apps-challenge that a route in web/app/ can answer.