create_addon
Provision a new Heroku add-on for your app by specifying the service, plan, and custom naming. Automates add-on setup and returns configuration details for easy integration.
Instructions
Create a new Heroku add-on for an application. Use this tool when you need to: 1) Provision a new add-on for your app, 2) Specify a particular service and plan, 3) Set a custom name for the add-on or attachment. The tool handles the provisioning process and returns the new add-on's details.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| app | Yes | Specifies the target Heroku app for add-on provisioning. Requirements and behaviors: 1) App must exist and be accessible to you with write permissions, 2) App region may affect which add-on services are available, 3) If app is in a Private Space, only add-ons compliant with the space requirements can be provisioned. The add-on will be provisioned directly to this app and config vars will be set automatically. | |
| as | No | Sets a custom local name for the add-on attachment in the app. Important details: 1) Must be unique within the app (no other attachment can use the same name), 2) Used as a prefix for config vars (e.g., "CUSTOM_NAME_URL" instead of "HEROKU_POSTGRESQL_URL"), 3) Makes the add-on easier to identify in app context (e.g., "as: DATABASE" is clearer than "postgresql-curved-12345"), 4) When omitted, Heroku generates a default name based on the add-on service. Best practice: Use meaningful names that indicate the add-on's purpose (e.g., "PRIMARY_DB", "CACHE"). | |
| name | No | Assigns a custom global identifier for the add-on instance. Key characteristics: 1) Must be unique across all add-ons in Heroku (not just your apps), 2) Can be used to reference the add-on from any app or context, 3) Useful for identifying the add-on in cross-app scenarios or automation, 4) When omitted, Heroku generates a unique name (e.g., "postgresql-curved-12345"). Best practice: Include app name or environment if using custom names (e.g., "myapp-prod-db"). | |
| serviceAndPlan | Yes | Specifies which add-on service and plan to provision. Format and behavior: 1) Required format: "service_slug:plan_slug" (e.g., "heroku-postgresql:essential-0"), 2) If only service slug provided, the default (usually the cheapest or free) plan will be selected, 3) Some plans may have prerequisites (e.g., inside a private space, specific regions). Use list_addon_services and list_addon_plans tools to discover available options. |
Implementation Reference
- src/tools/addons.ts:119-131 (handler)The core handler function for the 'create_addon' tool. It constructs a CommandBuilder for 'addons:create', adds flags for app, as, name, positional argument for serviceAndPlan, executes via herokuRepl, and processes output with handleCliOutput.
async (options: CreateAddonOptions): Promise<McpToolResponse> => { const command = new CommandBuilder(TOOL_COMMAND_MAP.CREATE_ADDON) .addFlags({ app: options.app, as: options.as, name: options.name }) .addPositionalArguments({ 'service:plan': options.serviceAndPlan }) .build(); const output = await herokuRepl.executeCommand(command); return handleCliOutput(output); } - src/tools/addons.ts:96-101 (schema)Zod schema defining and validating the input parameters for the create_addon tool.
export const createAddonOptionsSchema = z.object({ app: z.string().describe('Target app for add-on. Must have write access. Region/space affects availability'), as: z.string().optional().describe('Custom attachment name. Used for config vars prefix. Must be unique in app'), name: z.string().optional().describe('Global add-on identifier. Must be unique across all Heroku add-ons'), serviceAndPlan: z.string().describe('Format: service_slug:plan_slug (e.g., heroku-postgresql:essential-0)') }); - src/tools/addons.ts:114-133 (registration)Function that registers the 'create_addon' tool with the MCP server, including schema and inline handler.
export const registerCreateAddonTool = (server: McpServer, herokuRepl: HerokuREPL): void => { server.tool( 'create_addon', 'Create add-on: specify service, plan, custom names', createAddonOptionsSchema.shape, async (options: CreateAddonOptions): Promise<McpToolResponse> => { const command = new CommandBuilder(TOOL_COMMAND_MAP.CREATE_ADDON) .addFlags({ app: options.app, as: options.as, name: options.name }) .addPositionalArguments({ 'service:plan': options.serviceAndPlan }) .build(); const output = await herokuRepl.executeCommand(command); return handleCliOutput(output); } ); }; - src/index.ts:71-71 (registration)Invocation of the registration function for create_addon tool on the main MCP server instance.
addons.registerCreateAddonTool(server, herokuRepl); - src/utils/tool-commands.ts:26-26 (helper)Constant mapping CREATE_ADDON to the Heroku CLI command 'addons:create', referenced in the handler.
CREATE_ADDON: 'addons:create',