Build for the Ecosystem with Your Own Agent

Build SOIS extensions with the AI agent you already use (Claude, ChatGPT, Cursor, Gemini, or any MCP-capable tool). You connect your agent to the SOIS MCP server, build the extension on your own machine, then upload it for review and publishing. You use your own AI; SOIS charges nothing to build.

This is the ecosystem path. Anyone can build for the marketplace and earn from their apps. You do not need the developer portal to build a custom extension; connecting your agent is enough. The portal is where you publish to the marketplace and manage your payouts. See Monetise your apps for the revenue model.

How it works

  1. Connect your agent to your workspace's MCP server (OAuth, or a token).
  2. Build locally against the SOIS spec your agent reads over MCP.
  3. Validate with a free static check until it is clean.
  4. Upload the bundle. It is hardened, gated, and queued for review.
  5. Review and publish. Once approved, your extension is live in the marketplace.

Connect your agent

The build tools live on your workspace's own MCP server, the same endpoint covered in MCP Server. There is no separate build server to set up: you connect once, and because your account can build, the build tools appear in your agent's tool list automatically. They are admin-gated, so they only show for builder-capable accounts.

Server:     https://<your-workspace-host>/api/mcp
Discovery:  https://<your-workspace-host>/.well-known/mcp.json

Connecting: the recommended path is OAuth. Add the MCP URL to your client (Claude, ChatGPT, Cursor, and others); it discovers the sign-in and connects with nothing to paste. A Bearer token plus an X-Api-Key header also works for clients that do not do OAuth. See MCP Server for the full connect flow and discovery details.

Your agent then has the build tools available. Start every build by asking it to read the rules.

The build tools

Tool What it does
getExtensionRules The canonical manifest, migration, permission, toolkit, i18n, UI and security rules. Call this first.
getExtensionFrameSpec The host frame contract for local preview: the mount signature, theme tokens, REST api shape and bundle format.
createExtensionProject Create a new app project. Returns a project_id.
validateExtensionBundle Dry run the free static gate on your files and return issues to fix. Run it as often as you like.
uploadExtensionBundle Submit your bundle. It is hardened, gated, and on a pass queued for review.
getExtensionStatus The lifecycle status and latest validation report for a project.
listExtensionProjects Your projects and their status.

Bundle format

An extension is a small bundle of files:

File Purpose
manifest.json The single source of truth: id, entities, data model, permissions, files.
index.js The UI, written as a vanilla JavaScript IIFE that mounts via window.AppExtension.mount. No framework in the bundle.
toolkit.js Optional agent tools, following the examiner pattern.
permissions.json Permission keys that match your route names.
migrations/ Database tables named ext_{name}_{table} with an id and a data JSON column.
lang/ Locale files, every key prefixed ext_{name}.

Key rules your agent enforces from getExtensionRules:

  • Business fields live inside the data JSON column, not as separate columns.
  • No foreign keys across extensions, no DROP, TRUNCATE or dropColumn in a migration up(), no raw SQL, no shell or filesystem access.
  • Style the UI with the --ext-* theme tokens so it matches SOIS. Never hardcode colours or user facing text.

Validate before you upload

validateExtensionBundle runs the same free static gate the server runs on upload, so you can fix issues locally first. It checks file types, migration safety, manifest structure, naming and i18n. The server side gate is always authoritative: passing locally is a convenience, not a guarantee.

Upload, review, publish

When uploadExtensionBundle reports a pass, your bundle is stored in a private review area and your project moves to review. A reviewer checks it and either approves it, which publishes it to the marketplace, or returns it with feedback for you to fix and upload again.

Next steps