One directory per service under packages/<id>/, where <id> is lowercase
letters, digits and - (google-calendar, not googlecalendar). Copy the shape
of an existing package:
| Interface the service offers | Copy |
|---|---|
| Remote MCP server with one-click sign-in | packages/linear (MCP + GraphQL), packages/posthog |
| Public OpenAPI/Swagger document | packages/resend, packages/github (OAuth + token) |
| GraphQL API | packages/linear |
| Remote MCP server, nothing better | see "MCP servers" below |
| None of the above | queries/mutations with fetch |
Expose as many working tools as possible. Prefer, in order:
- The vendor's official remote MCP server when signing in to it needs no OAuth app of the user's own: the probe shows dynamic client registration or Client ID Metadata Documents, or Executor has a first-party client for its authorization server (GitHub). Any other OAuth method makes a Cloud user register an app first, and people stop there. Drop OAuth methods that need a user-owned app; keep the API-key methods and, for the accounts whose credentials it accepts, the OpenAPI/GraphQL router (MCP tokens usually work only on the MCP server).
- The vendor's official OpenAPI document at a stable public URL (check
integrations.sh's
domains/<domain>/integrations.jsonspecfield, the vendor's docs and GitHub). It must cover the API users expect; a stub with five operations loses to a good MCP server. - The vendor's GraphQL API when it is the primary API.
- The vendor's official remote MCP server.
- Hand-written tools with
fetchfor the 10–30 operations people use most.
One product is one package, even when the vendor splits its API into several
specs (Algolia's search, analytics, insights...): mount each spec under its own
key in one router, with one provider. A product's MCP server belongs in the
same package as its API: build or extend packages/<x> (no mcp suffix),
mounting the MCP server under an mcp key beside the API's api key. Use one
provider for both, so the app has one account slot and its first sign-in is the
one-click one; route each account to the interfaces its method works on. Never
use an unofficial or community spec or MCP server without saying so in the
README.
Auth is the part that must be right. The vendor's own docs are the authority; say in the README when a detail could not be confirmed there.
- Offer every method a normal user can complete themselves: usually an API key
(
secrets) and, when the vendor supports user-created OAuth apps,oauth2. The connect page starts with the first OAuth method, so a one-click method (an MCP server with registration, or one Executor has a first-party client for) goes first. Executor's GitHub App is offered only to a method on github.com's own authorize and token endpoints that declares no scopes. - OAuth: use
discoverwhen the vendor publishes RFC 8414/OIDC metadata; otherwise declareauthorizationUrl,tokenUrl,tokenEndpointAuthMethod,scopesand any quirks (scopeSeparator,tokenRequestFormat,tokenResponse,authorizationParams,revocationUrl). Pick scopes that cover the generated tools without asking for admin. - With
discover, leavescopesout by default. Executor requests the MCP challenge'sscope, else the protected-resourcescopes_supported, plusoffline_accesswhen the authorization server lists it. Declarescopesonly when that misses scopes the tools need (an issuer-onlydiscoversuch as Google or Microsoft, or a server that advertises none) or asks for admin scopes the tools do not use, and say which in a comment. Never declare a scope the server does not advertise: Descript'sfull_accessbroke every sign-in. - A method's
labelis its short name, not its instructions. The connect form shows it as the method's name in the "Sign-in method" menu, and the fix prompt for a failed account check names it ("failed for my Twilio credentials (sign-in method: API key)"), so it must read as a name. Use two to four words, at most 40 characters (scripts/check.shfails longer ones), and the same name other apps use for the same kind of credential. Good: "API key", "Personal access token", "API key and secret", "Auth token or API key". Bad: "API key (from tinify.com/dashboard/api)", "API key for one Abstract product (product: email-reputation, ...)", or any sentence. Put where to find each value in the method'sguide(Markdown the form shows above the fields), and what goes in each field in that field'stitleanddescription. - A label is part of a provider's identity today; the guide and each field's
titleanddescriptionare not. Changing the label on a published app makes a new provider, which strands the accounts people have already connected: they no longer fit the app and stay linked where nobody can see them. Choose a short label when the app is first written, and do not rename labels on existing apps.scripts/check.shlists the existing packages whose long labels stay as they are. - Declare
hostswith every host credentials go to. - Give the provider a
healthcheck on a read-only current-user/account endpoint, decoding only fields that are always present (the schema builders have no optional or nullable). For MCP providers usemcpHealth. - Approvals: every OpenAPI/GraphQL mutation gets
always(); MCP tools getalways()unlessreadOnlyHint === true.
package.json:"name": "@executor.sh/<id>",description,"private": true,"type": "module","executor": { "title": "<Product name>" },dependencies.appsexactly0.0.1-beta.140(plusgraphql16.11.0or@modelcontextprotocol/sdk1.32.1when used). A package that needs an option from a later version pins that version and is listed inscripts/check.sh:linkedinandlinkedinadspin0.0.1-beta.142forpkce: false. The rootappsdevDependency, whichtsc -p .checks every package against, is the latest version any package pins.index.ts: declares the icons beside the accounts,defineApp({ accounts: { ... }, icons }, ...), and wraps the tools inrouter(..., { title, description, icons }), addinginstructionsonly for non-obvious usage rules. The dashboard reads the app's icons fromdefineAppwithout evaluating the app; without them an installed app falls back to the catalog or a generic domain logo.openapi.tsfor OpenAPI packages (exportsoptions, used byscripts/tools.ts).icon.ts, generated:node scripts/icon.ts <id> <simple-icons-slug>ornode scripts/icon.ts <id> path/to/official-logo.svg.README.md: one paragraph on what it covers, the interface and its source URL, each auth method and where the user creates the key/OAuth app (including the redirect URI note for OAuth), and known gaps.
The icon must be the product's own mark: Gmail's envelope, not Google's G;
Google Drive's triangle, not Google's G; Azure DevOps, not Microsoft. Find the
product in Simple Icons (node -e 'const s=require("simple-icons");console.log(Object.values(s).filter(i=>/gmail/i.test(i.title)).map(i=>i.slug+" "+i.title))').
If Simple Icons lacks it, download the vendor's official SVG logo from its press
or brand page into a fresh directory under /tmp, check it is an SVG of the
product mark (not a wordmark when a mark exists), and pass that path. If the
vendor publishes no SVG, use its official PNG logo or app icon at 128px or
larger (node scripts/icon.ts <id> logo.png); never ship an empty icons.
Never use a 16/32px favicon, a third-party logo service, a generic glyph (an
envelope for an email product), or a parent company's logo.
defineApp accepts at most 8 icons totalling 32 KiB of JSON (base64
included) and refuses the package otherwise; scripts/icon.ts and
scripts/check.sh enforce this. Pass an SVG through bunx svgo --multipass,
or a PNG at 128px (magick logo.png -resize '128x128>' -strip logo-128.png).
scripts/icon.ts draws near-black marks white in the dark variant. Render both
variants (scripts/icon-preview.sh <id> writes a PNG of each on white and on
#111) and look at them: the mark must be fully visible on both.
import { defineApp, defineProvider, oauth2, router, toolAnnotations, withApprovals, accountRouter } from "apps";
import { mcpHealth, mcpRouter } from "apps/mcp";
import { always } from "apps/operations/approval";Probe first: node scripts/mcp-probe.ts <url>. oauth means declare
oauth2({ discover: url }) and trust the server's metadata. It connects in one
click only when registration_endpoint or
client_id_metadata_document_supported is set; otherwise it needs a user-owned
OAuth app like any other. Check the vendor's docs for an allowlist of approved
MCP clients (Vercel has one) before relying on registration. Anything else: read
the vendor's docs for the header it expects. The probe is the only check for MCP
packages besides typecheck and deploy.
Run scripts/check.sh <id>. It typechecks the package, compiles an OpenAPI
document and reports tool counts, and deploys to the throwaway local Executor.
An OpenAPI package with zero tools, or with many skipped operations you have not
explained, is not done. Large multiple_hosts skips usually mean the spec
spans several origins; note them in the README.
Do not connect real accounts or call vendor APIs with credentials.
Add the package to catalog/apps.json as { "id": "<id>", "category": "<category>" }
(category optional). The feed lists apps in that file's order, so place it near
comparable products. Packages not listed there are not published.