Build your first app
Create an app folder with the scaffold command, then replace its unfinished fields.
Generate the files
Section titled “Generate the files”Select a method and run the matching command from the repository root. Replace example addresses, package names, and credential names with provider values.
MCP server
Section titled “MCP server”pnpm create:app my-app --type mcp --name "My App" --url https://mcp.example.com/mcp --auth oauth2MCP is the default when --type is omitted. Select oauth2, bearer, or x-api-key authentication.
HTTP API
Section titled “HTTP API”pnpm create:app my-app --type http --name "My App" --url https://api.example.com/v1 --auth bearerSelect oauth2, bearer, or x-api-key. Use the API examples for custom key headers, OAuth metadata, and GraphQL read checks.
Command-line tool
Section titled “Command-line tool”pnpm create:app my-app --type cli --name "My App" --command mycli --npm @provider/[email protected] --env PROVIDER_TOKEN --auth envSelect one pinned source: --npm <package@version>, --pypi <package==version>, or --download <binary-url> --sha256 <digest>. Repeat --env for each required credential. Give each field a clear label in the generated app file.
The command rejects invalid options, unsafe addresses, and unpinned CLI sources. It writes files only. It does not contact providers or install commands. The example addresses are reserved and must be replaced before running the command.
All methods use this layout. Only fixed MCP apps include mcp.json:
src/apps/my-app/ plugin.json mcp.json io.n8n.nod/ app.json contract.jsonThe command refuses to replace an existing directory. The generated placeholders deliberately fail validation until you complete them.
Complete the manifest
Section titled “Complete the manifest”Set the maintainer, description, and version in plugin.json. Keep its Nod reference unchanged.
Edit io.n8n.nod/app.json:
- Set the display name.
- Add concrete example requests in
prompts. - State account, plan, scope, and provider-version requirements.
- State unsupported behavior in
limitations. - Complete the typed connection fields for the selected method. Add OAuth scopes only when the provider requires them.
For an icon, add io.n8n.nod/icon.svg and set icon to ./io.n8n.nod/icon.svg. PNG and WebP are also supported. Keep the image under 128 KB. Use letters, digits, underscores, or hyphens in asset names.
Keep the generated $schema values. Editors that support JSON Schema use them for field completion and error checks. CI uses the same definitions.
Do not put tokens, passwords, private server addresses, or customer data in these files.
Complete the required fixture
Section titled “Complete the required fixture”Edit io.n8n.nod/contract.json. Set source to the provider documentation. Complete the read tool, HTTP request, or CLI argument array. Use synthetic response data.
API and CLI apps use this same read operation to verify access during setup. The offline framework uses synthetic responses or a controlled child process. It never calls the real provider. See Test the app.
Add a guide when needed
Section titled “Add a guide when needed”Use skills/<app-id>/SKILL.md for procedures the model cannot infer from the interface. API and CLI apps should describe supported operations and link to provider references. Keep required name and description frontmatter. Put detailed procedures in Markdown reference files.
App skills load with Nod's other guides. Skill names must be unique across the complete library. Credentials and permissions stay in the runtime.
Check and preview
Section titled “Check and preview”pnpm check:apps my-apppnpm devOpen Apps and find the new entry. Review setup without connecting a private account. Run the docs build and preview its catalog page:
Nod reads app definitions at startup. Restart the development server after changing an app folder.
pnpm --dir docs install --frozen-lockfilepnpm --dir docs buildpnpm --dir docs previewThe page appears at /docs/connect/community-apps/my-app/. Its social image is social.png under that address.
Use an instance address
Section titled “Use an instance address”Copy n8n's connection shape when users supply their own server address. Use an owner-supplied endpoint in the Nod extension and omit mcp.json. See Format reference.
Only n8n currently uses private or local instance addresses. A new app cannot enable private network access through its manifest.