list_addons
List and filter Heroku add-ons across apps, retrieve detailed metadata in JSON, and view add-ons for specific apps using flexible filtering options.
Instructions
List Heroku add-ons with flexible filtering options. Use this tool when you need to: 1) View all add-ons across your apps, 2) List add-ons for a specific app, 3) Get detailed add-on metadata in JSON format.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Forces the tool to list all add-ons across all apps accessible to the user. When true, this flag: 1) Overrides any default app setting from Git remote configuration, 2) Ignores the app flag if provided, 3) Shows a comprehensive list including: app name, add-on name, service plan, billing status, and provisioning status for each add-on. When false or omitted, respects the default app setting and the app flag. | |
| app | No | Specifies a single Heroku app whose add-ons you want to list. Important behaviors: 1) When provided, shows add-ons and attachments only for this specific app, 2) When omitted, falls back to the default app from Git remote if configured, 3) If no default app exists, lists add-ons for all accessible apps, 4) This flag is completely ignored when all=true. The response includes both provisioned add-ons and add-on attachments from other apps. | |
| json | No | Controls the response format and detail level. When true, returns a structured JSON response containing: 1) Complete add-on metadata including ID, name, and creation timestamp, 2) Detailed plan information including tier and cost, 3) Configuration variables set by the add-on, 4) Attachment details if the add-on is shared with other apps, 5) Billing and compliance status information. When false or omitted, returns a human-readable text format with basic information. |
Implementation Reference
- src/tools/addons.ts:40-50 (handler)Handler function for 'list_addons' tool: builds Heroku CLI command using CommandBuilder with LIST_ADDONS ('addons'), adds flags from options, executes via herokuRepl, and processes output.async (options: ListAddonsOptions): Promise<McpToolResponse> => { const command = new CommandBuilder(TOOL_COMMAND_MAP.LIST_ADDONS) .addFlags({ all: options.all, app: options.app }) .build(); const output = await herokuRepl.executeCommand(command); return handleCliOutput(output); }
- src/tools/addons.ts:13-22 (schema)Zod schema defining optional 'all' boolean and 'app' string parameters for the list_addons tool.export const listAddonsOptionsSchema = z.object({ all: z .boolean() .optional() .describe('List all add-ons across accessible apps. Overrides app param, shows full status'), app: z .string() .optional() .describe('Filter by app name. Shows add-ons and attachments. Uses Git remote default if omitted') });
- src/tools/addons.ts:35-52 (registration)Registration function that registers the 'list_addons' tool on the MCP server with name, description, schema, and handler.export const registerListAddonsTool = (server: McpServer, herokuRepl: HerokuREPL): void => { server.tool( 'list_addons', 'List add-ons: all apps or specific app, detailed metadata', listAddonsOptionsSchema.shape, async (options: ListAddonsOptions): Promise<McpToolResponse> => { const command = new CommandBuilder(TOOL_COMMAND_MAP.LIST_ADDONS) .addFlags({ all: options.all, app: options.app }) .build(); const output = await herokuRepl.executeCommand(command); return handleCliOutput(output); } ); };
- src/index.ts:69-69 (registration)Invocation of registerListAddonsTool during server initialization, passing McpServer and HerokuREPL instances.addons.registerListAddonsTool(server, herokuRepl);
- src/utils/tool-commands.ts:24-24 (helper)TOOL_COMMAND_MAP constant mapping LIST_ADDONS to Heroku CLI command 'addons', used by CommandBuilder in handler.LIST_ADDONS: 'addons',