App Builder MCP Tools Reference

The Komodo MCP server registers 26 App Builder tools (15 app development + 6 secrets + 5 sharing) and appends detailed workflow instructions to its prompt. AI assistants connected to the MCP server can scaffold, build, deploy, manage, and share Komodo Apps with minimal user input. Tools operate against production.

Recommended Workflow

The MCP server’s built-in instructions guide AI assistants through this workflow:

1. get_available_templates — Always call first. Returns available templates (FastAPI, Streamlit, React, multi-container, react-advanced, restate-agent) so the assistant can recommend the right one. For Restate devfile fields, callback paths, and registration behavior, see Durable workflows (Restate).

2. scaffold_app — Generate the project from the selected template: source code, Dockerfile, devfile.yaml, and README.

3. validate_devfile — Always validate before building. Catches schema errors, missing fields, port mismatches, and invalid app names early.

4. register_app — Pre-register the app (name, display name, project_path so a .app file is written). Required before build_app when the app uses Komodo secrets (app-scoped or otherwise): RBAC/FGA needs the app Custom Resource before secret operations behave reliably. If the app does not use secrets, pre-registration is still recommended; build_app can create the app inline if you skip it (legacy flow).

5. build_app — By default, package the project and build via the remote Build API (platform worker, ECR, signing); only Komodo OAuth is required. Set build_mode to local to run BuildKit on the client (buildctl → docker image tar), then upload via the Build API prebuilt path (Trivy, ECR, and signing still run on the platform). No AWS_ROLE_ARN or client-side registry push. Then create or update the app in Komodo (or update the app pre-registered in step 4 when .app is present).

6. After build_app — Print the app_id and every entry in service_urls (one URL per service). Then ask whether the user wants you to poll deployment.

7. get_app_status — Only if the user asks you to check deployment: poll every 10-15 seconds until the app reaches RUNNING or FAILED. If failed, call get_app_logs to diagnose.

Build Verification

After build_app, the assistant should:

• Verify success: true and a valid app_id in the response
• Retry up to 2 times on transient errors (timeouts, network issues)
• On remote Build API or local BuildKit / prebuilt-upload failure, inform the user and retry
• On app create failure, inspect the error message

Multi-Container Deployment

For multi-container and react-advanced templates, all services are managed as a single app with one root devfile.yaml and one app_id. When build_app runs from the project root:

• All service images are built in parallel (shared build context)
• Images are registered in dependency order (from dependsOn)
• The response includes build_ids, image_uris, deploy_order, and service_urls

To rebuild a single service, pass service_name to build_app. The assistant should print every entry in service_urls (one URL per service) after a successful build.

See the App Builder guide for devfile structure, service URL templating, and cross-service communication rules.

---

Scaffolding & Configuration Tools

scaffold_app

Create a new Komodo application from a template. Generates all project files including application source code, Dockerfile, devfile.yaml, and README.md.

Parameters:

Name	Type	Required	Description
app_name	string	yes	Application name (lowercase, alphanumeric + hyphens, 1-63 chars, starts with letter)
app_type	string	yes	Template: fastapi, streamlit, react, multi-container, react-advanced, restate-agent
output_directory	string	yes	Directory to scaffold into
description	string	no	App description for devfile metadata
display_name	string	no	Human-readable display name
port	integer	no	Override the template’s default port
fabrics	list[string]	no	Komodo fabrics for the app
permissions	list[string]	no	Komodo permissions for the app
overwrite	boolean	no	Overwrite existing files (default: false)
restate	boolean	no	When true, applies the Restate overlay after scaffolding (devfile restate block, restate-sdk, ASGI router / example workflow for Python). Also applied automatically when app_type is restate-agent. See Durable workflows (Restate).

Returns: Project path and list of files created.

get_available_templates

List all available application templates with metadata.

Returns: Array of templates, each with name, description, language, and default_port.

Template	Language	Default Port
fastapi	Python	8002
streamlit	Python	8501
react	JavaScript	80
multi-container	Python	8000
react-advanced	JavaScript	3000
restate-agent	Python	9080

validate_devfile

Validate a devfile against the Komodo schema. Checks:

• YAML syntax
• Required fields (schemaVersion, metadata.name, metadata.displayName)
• Component structure and endpoint configuration
• Komodo-specific fields (fabrics, permissions)
• App name validity (lowercase, 1-63 chars, starts with letter, no consecutive hyphens)

Parameters:

Name	Type	Required	Description
devfile_content	string	no	Raw YAML string (provide either this or devfile_path)
devfile_path	string	no	Path to a devfile.yaml file

Returns: { valid: boolean, errors: string[], warnings: string[] }

generate_devfile

Generate a devfile.yaml for an existing project without scaffolding full application code.

Parameters:

Name	Type	Required	Description
app_name	string	yes	Application name
display_name	string	yes	Human-readable name
description	string	yes	App description
port	integer	no	Container port (default: 8002)
language	string	no	Language hint (default: python)
dockerfile_path	string	no	Path to Dockerfile (default: Dockerfile)
build_context	string	no	Docker build context (default: .)
fabrics	list[string]	no	Komodo fabrics
permissions	list[string]	no	Komodo permissions
output_path	string	no	Write the generated file to this path

Returns: Generated devfile content and output path (if written).

---

Build & Deploy Tools

register_app

Pre-register a Komodo application before the first build_app. Reserves the name, creates the service principal, and registers RBAC so identity exists before image build. When project_path is set, writes a .app file with app_id so build_app updates that app instead of creating a new one.

Parameters:

Name	Type	Required	Description
name	string	yes	Machine-readable app name (lowercase, alphanumeric + hyphens)
display_name	string	yes	Human-readable display name
project_path	string	no	Directory for the .app file; omit if you will pass app_id to build_app manually
description	string	no	App description

build_app

Build and deploy a Komodo application. This is the primary deployment tool.

Default (build_mode omitted or remote): packages the project directory, uploads context through the Build API, runs the image build on Komodo infrastructure (worker, ECR push, signing). Only Komodo OAuth is required — no user AWS credentials.

Optional build_mode: local: runs BuildKit / buildctl on the client to produce a docker image tarball, uploads it through the Build API as prebuilt, then the worker scans, pushes to ECR, and signs — same OAuth as remote. Requires buildctl on PATH and a reachable BuildKit at BUILDKIT_HOST. No user AWS credentials or ECR push from the client.

BUILDKIT_HOST (local builds): Default docker-container://buildkitd when unset. Use tcp://127.0.0.1:1234 if you start BuildKit with docker run ... -p 1234:1234 (see App Builder — BUILDKIT_HOST). For MCP, set this on the MCP server environment (Cursor MCP config), not only in the user’s shell — otherwise build_app may report BuildKit unreachable while komodo build --local works in a terminal with export BUILDKIT_HOST=....

After a successful image build, updates devfile.yaml with imageUri and creates or updates the app (tracked via .app file).

Parameters:

Name	Type	Required	Description
project_path	string	yes	Path to the project directory (must contain Dockerfile and devfile.yaml)
environment	string	no	production (default, from session)
verbose	boolean	no	Show detailed build output (default: false)
architecture	string	no	Target arch for local builds: amd64 or arm64 (default: amd64)
build_mode	string	no	remote (default) or local
service_name	string	no	For multi-container projects: rebuild only this service. Omit to build all services.

Returns (single-service): { success, app_id, app_url, build_id, image_uri, ... }

Returns (multi-service): { success, app_id, app_url, build_ids, image_uris, deploy_order, service_urls, rollout_waited: false, ... }

Field	Description
build_ids	List of build job IDs (one per service)
image_uris	Map of service name → ECR image URI
deploy_order	Services in dependency order
service_urls	Map of service name → public HTTPS URL

Use get_app_status with app_id for deployment state (RUNNING, FAILED, etc.). The response may include build_id / build_ids for image build jobs; use cancel_build or get_build_scan_report with those IDs, not get_app_status.

get_build_scan_report

Fetch the Trivy vulnerability scan JSON for an image build job.

Parameters: build_id (from build_app), optional environment.

Returns: { success, build_id, report?, error? }

cancel_build

Cancel a queued or in-progress image build job (Build API). Does not stop a running deployed app.

Parameters: build_id, optional environment.

---

App Management Tools

list_apps

List all Komodo applications for the current account.

Parameters:

Name	Type	Required	Description
environment	string	no	Target environment
page_size	integer	no	Results per page (default: 20)
next_page_token	string	no	Pagination token from previous response

Returns: Array of apps with name, status, URL, and timestamps. Includes pagination token if more results are available.

get_app

Get full details of a specific app including its devfile configuration.

Parameters:

Name	Type	Required	Description
app_id	string	yes	App UUID
environment	string	no	Target environment

Returns: App details including name, description, status, URL, devfile, enabled state, and timestamps.

get_app_status

Check whether an app is running, deploying, suspended, or failed. Use this to poll deployment progress after build_app.

Parameters:

Name	Type	Required	Description
app_id	string	yes	App UUID
environment	string	no	Target environment

Returns: { status: string, app_url: string }

get_app_logs

Retrieve logs for debugging deployment failures or runtime errors. Returns presigned S3 URLs for log content. For multi-service apps, pass service_name to get logs for a specific service.

Parameters:

Name	Type	Required	Description
app_id	string	yes	App UUID
environment	string	no	Target environment
latest_only	boolean	no	Only return the most recent logs (default: true)
service_name	string	no	Filter logs to a specific service (multi-container apps)

Returns: Array of log entries with presigned URLs.

---

Lifecycle Tools

enable_app

Resume a previously suspended app. After calling, poll get_app_status until the app is RUNNING.

Parameters:

Name	Type	Required	Description
app_id	string	yes	App UUID
environment	string	no	Target environment

disable_app

Suspend a running app without deleting it. The app can be re-enabled later. Useful for pausing apps that are not actively needed to save resources.

Parameters:

Name	Type	Required	Description
app_id	string	yes	App UUID
environment	string	no	Target environment

delete_app

Permanently delete an app. This cannot be undone. After deleting, also delete the .app file from the project directory to avoid 404 errors on subsequent builds.

Parameters:

Name	Type	Required	Description
app_id	string	yes	App UUID
environment	string	no	Target environment

---

Secrets Tools

Store and manage secrets via the Komodo Secrets Service. Secrets are stored server-side in a hardened vault and can be scoped to a user, an application, or shared across the organization.

Scope	secret_type value	Description
Personal	user	Private to the authenticated user
Application	app	Tied to a specific app (requires app_id)
Organization	shared	Accessible by all account members

create_secret

Store a new secret at the given path.

Parameters:

Name	Type	Required	Description
secret_type	string	yes	user, app, or shared
secret_path	string	yes	Path for the secret (e.g. my-api-key or db/password). Must not start with / or contain ..
data	string	yes	JSON string of key-value pairs to store (e.g. '{"password": "s3cret"}')
app_id	string	when app	App UUID (required for application secrets)
metadata	string	no	JSON string of metadata key-value pairs

get_secret

Read a secret’s value and metadata.

Parameters:

Name	Type	Required	Description
secret_type	string	yes	user, app, or shared
secret_path	string	yes	Path of the secret to read
app_id	string	when app	App UUID

list_secrets

List secret paths within a scope, with optional prefix filtering and pagination.

Parameters:

Name	Type	Required	Description
secret_type	string	yes	user, app, or shared
prefix	string	no	Filter results to paths starting with this prefix (e.g. db/)
app_id	string	when app	App UUID
next_token	string	no	Pagination token from a previous response

update_secret

Replace a secret’s data and optionally its metadata. Creates a new version.

Parameters:

Name	Type	Required	Description
secret_type	string	yes	user, app, or shared
secret_path	string	yes	Path of the secret to update
data	string	yes	JSON string of new key-value pairs
app_id	string	when app	App UUID
metadata	string	no	JSON string of new metadata

delete_secret

Permanently remove a secret. This cannot be undone.

Parameters:

Name	Type	Required	Description
secret_type	string	yes	user, app, or shared
secret_path	string	yes	Path of the secret to delete
app_id	string	when app	App UUID

share_secret

Copy a secret into the shared (organization-wide) namespace so any account member can access it. The original secret is not modified.

Parameters:

Name	Type	Required	Description
from_secret_type	string	yes	Source scope: user, app, or shared
from_secret_path	string	yes	Path of the source secret
to_shared_path	string	yes	Destination path under the shared namespace (e.g. team-api/credentials)
app_id	string	when app	App UUID (if source is an app secret)
copy_metadata	boolean	no	Copy source metadata to the shared copy (default: true)

---

App Sharing / Permissions Tools

View and manage who has access to your Komodo apps via Platform RBAC custom resource roles. Each app is backed by a custom resource whose ID is the app UUID. The assistant uses these tools only when you explicitly ask to view, grant, or revoke app access.

list_grantable_roles

Return the roles the current user is allowed to grant on an app. The result depends on the caller’s own role (e.g. an owner can grant owner, editor, and viewer; an editor can grant editor and viewer).

Parameters:

Name	Type	Required	Description
app_id	string	yes	App UUID

Returns: { success, roles: ["owner", "editor", "viewer"] }

list_app_permissions

List all users who currently have access to an app and their roles.

Parameters:

Name	Type	Required	Description
app_id	string	yes	App UUID

Returns: { success, users: [{ user_id, email, name, role }] }

grant_app_role

Grant a role on an app to another user.

Parameters:

Name	Type	Required	Description
app_id	string	yes	App UUID
role	string	yes	Role to grant: owner, editor, or viewer
user_id	string	yes	Target user UUID or email

Returns: { success, message }

revoke_app_role

Revoke a role on an app from a user.

Parameters:

Name	Type	Required	Description
app_id	string	yes	App UUID
role	string	yes	Role to revoke
user_id	string	yes	Target user UUID or email

Returns: { success, message }

list_account_users

List all users in the current account. Useful for discovering user IDs and emails before granting roles.

Returns: { success, users: [{ id, email, name }] }