How to connect Porter MCP with Codex

Check whether an AWS cloud account has quota (vCPUs, elastic IPs, NAT gateways, VPCs, availability zones) to provision a Porter cluster in a region. Run before create_cluster, which does not reject on insufficient quota: each failed check reports usage against the limit and the AWS console link where the user can request an increase, and quota increase requests already open with AWS are listed when quota is insufficient. Omit node_groups to check the node groups create_cluster provisions, or pass the node groups an existing cluster will be updated to. A cloud account on any other provider returns status not_applicable. Accepts a project ID or exact name and a cloud account ID.

Connect a cloud account to a Porter project and return the one action that advances the connection. For AWS and GCP it returns immediately without waiting, so poll get_cloud_account_status until state is connected; for Azure the final call connects the subscription before it returns. Safe to call repeatedly: the server is idempotent per account, so retrying never creates a duplicate account, and only gcp.reissue_setup_command invalidates an access grant already handed out. If the user has not named an account, omit the provider details object entirely: the response explains how to discover the account ID and confirm it with the user. The access grant must be applied in the account being connected; applying it in a different account leaves the connection waiting forever. For Azure, call once with only azure.subscription_id to get the setup script command, run it for the user, then call again adding the azure.client_id and azure.tenant_id it printed. For GCP, call once with gcp.project_id: the response carries the Cloud Shell url and the cloud_shell_command the user pastes there, which you never run. Calling again while the setup is pending returns poll_status without a new command; set gcp.reissue_setup_command only when the command expired or was lost. Azure and GCP support stops at the connected account: Porter cannot create clusters in an Azure subscription or a GCP project through these tools yet, so say so before connecting one for a user whose goal is a cluster.

Check whether Porter can reach a GitHub repository and return the browser action required to connect it.

Report the Slack channels connected to a Porter project, or return the browser URL that connects one. The channel is chosen on Slack's own install screen, not through this tool. After the user returns from the browser, call it again to confirm the connection. Accepts a project ID or exact name.

The recommended way to create a Porter application is to provide GitHub source and a build configuration. Before using that flow, call connect_github with the repository; proceed only when next_step is none, and otherwise return the tool's URL and message to the user instead of creating the application. In this flow, Porter initially creates the application with its placeholder image and opens a GitHub Actions workflow pull request; merge the pull request to build and deploy the application's code. Use image only when the deployable image already exists. Use build without source or image only for local development; the response includes a local_build_command field with the porter apply invocation to run from the local repository. Fails if an application with the same name already exists in the target project or cluster. Never updates an existing application; use update_application instead. Resolves the deployment target from cluster and optional namespace, defaulting to the cluster's default deployment target. Omit cluster only to deploy on Porter Cloud: when get_project reports porter_cloud_enabled is true and the user has agreed, Porter assigns the project a ready cluster (the same one on every later call) and deploys to it in this call.

File quota increase requests with AWS for every quota check_aws_cluster_quota would fail for a cloud account in a region, sized to cover current usage plus the cluster. Quotas with a request already pending or approved are reported, not re-filed. Call after check_aws_cluster_quota reports insufficient quota and the user agrees to request increases; AWS approval is asynchronous and takes anywhere from an hour to a day or more, so tell the user to expect a wait, poll list_aws_quota_requests, and re-run check_aws_cluster_quota before create_cluster. Omit node_groups to request for the node groups create_cluster provisions. AWS only: a cloud account on any other provider is an error. Accepts a project ID or exact name and a cloud account ID.

Provision a new Porter cluster into a connected AWS cloud account (the provider is inferred from the account; GCP and Azure accounts are not supported yet and return an error). Porter picks the Kubernetes version, node groups, and network CIDRs; only a name and region are needed. Call check_aws_cluster_quota for the same cloud account and region first and do not create when it reports insufficient quota: a quota shortfall does not reject the create, Porter files the increase request with AWS and provisioning waits up to 90 minutes for approval. Other preflight failures, such as unavailable availability zones or conflicting CIDRs, reject the create and name the failing checks in the error. Provisioning is asynchronous: the cluster is returned before it is ready, so poll get_clusters for status. Accepts a project ID or exact name and a cloud account ID.

Create or re-create the GitHub Actions workflow pull request for a Porter application. Porter generates the workflow YAML, opens a PR in the application's GitHub repository, and configures the required GitHub secrets. Use this when create_app returned a placeholder application without a PR URL (the workflow PR creation failed), or when an existing application is missing its workflow PR. Returns the pull request URL to merge for building and deploying the application's real code.

Create a Porter project owned by the caller and return its identifier. Not idempotent: every call creates a new project, so a retry leaves a duplicate behind. Confirm the name with the user before calling, and reuse an existing project from get_projects when one already fits.

Create a sandbox, an isolated container started from an image, on a Porter cluster that has sandboxes enabled. The call may return before the sandbox is running: poll get_sandbox until phase is running, then run commands with exec_sandbox. Put secrets in env, never in exec_sandbox commands. allowed_destinations restricts outbound traffic and needs egress_enabled on the cluster, see update_sandbox_settings. An image that cannot be pulled fails this call. Accepts a cluster name or ID. Requires project.

Uninstall an addon from a Porter cluster and remove its configuration, including the deploy token Porter issued for it. The addon's workloads stop before the call returns; its Postgres database is not touched, since the caller supplied it. Use it to clear a failed install before installing again, or when the user asks to remove QM. Confirm with the user first. Fails if the addon does not exist.

Enable sandboxes on a Porter cluster, which adds a sandbox node group and installs the sandbox runtime. Only AWS EKS clusters that have finished provisioning are supported. The call returns before the runtime is up: poll get_sandbox_settings until ready is true, then use create_sandbox. Safe to call again; already_enabled reports that nothing changed. There is no tool to disable sandboxes. Accepts a cluster name or ID. Requires project.

Run a command in a running sandbox on a Porter cluster that has sandboxes enabled, and return its stdout, stderr, and exit code. A non-zero exit_code is a normal result, not a tool error. The sandbox must be in phase running; check with get_sandbox. Each stream is capped to its last 32 KB, with truncated=true when either was cut, so for large output redirect to a file inside the sandbox and read slices with head, tail, or grep. Keep commands under about a minute; for longer work start it in the background with output redirected to a file, then poll with short commands. Commands are recorded in the sandbox's event log, so never put secrets in a command; pass them as env at create_sandbox. Accepts a cluster name or ID. Requires project.

Report where an addon on a Porter cluster is in its install, changing nothing. Poll it after install_addon or update_addon, waiting between calls, until status is installed, waiting_for_sso, or failed. waiting_for_sso means QM runs but oidc sign-in has no client ID yet; read error_message first, and if it is empty finish sign-in with update_addon. not_found is a status, not an error, so it is safe to poll after delete_addon.

List the addons installed on a Porter cluster with each addon's type, install status, and, for QM, its URL and sign-in state. Accepts a cluster name or ID. Requires project. Call before install_addon to see whether QM is already there.

Fetch capped runtime logs for a Porter app. Filter by time window, service, revision, search, pod/container. Requires project. Returns truncated=true when capped.

Return configuration for a Porter app and its services. Accepts an app name or UUID. Requires project. Never returns variables, secrets, or environment_groups.

Query one time-series metric for one Porter application service. Returns resolved context, the effective bounded UTC query, and normalized series without diagnoses or summaries.

List revisions for a Porter app (newest first), returning up to 50 at a time with cursor pagination. Accepts an app name or UUID. Requires project.

Return status for a Porter app: resolved IDs plus current revision and process health. Accepts an app name or UUID. Requires project. Does not include revision history, logs, or notifications.

List applications in a Porter project with cursor-based pagination, optionally filtered by name or deployment target. Accepts a project ID or exact name. Each response is one page; pass nextCursor as cursor with the same project to continue until nextCursor is omitted. The cursor preserves the original filters.

Report which stage of its build and deploy pipeline a Porter app is in: the latest build, pre-deploy, and deploy step, each progressing, success, or failed. Poll it to follow a deploy, for example after create_app's workflow pull request is merged, until every step is success or one is failed. Steps are the latest of each kind and can come from different pipeline runs, so compare commit_sha before reading them as one run. Accepts an app name or UUID. Requires project. Does not include build logs.

Report where a cloud account sits in the Porter connect flow, changing nothing. This is the polling companion to connect_cloud_account: poll it and follow next_step, rather than polling for one fixed state. Before Porter has created the cloud account this tool tops out at cloudformation_applied (AWS), awaiting_azure_setup (Azure), or awaiting_gcp_bootstrap (GCP) with next_step call_connect_cloud_account: only connect_cloud_account creates the account, so polling alone never reaches connected. Once an AWS account exists, poll until state is connected or not_connected; setup normally takes under a minute, and Porter gives up after 90 minutes. An Azure subscription connects synchronously inside connect_cloud_account, so its state never changes on its own: report it once and act on next_step rather than polling. A GCP project stays awaiting_gcp_bootstrap until the user has run the setup command in Cloud Shell, then moves to finalizing_connection while percent_complete rises, then connected; the setup command stops working 30 minutes after connect_cloud_account handed it out.

List node groups in a Porter cluster, including autoscaling bounds and cost-optimization (Karpenter) status. Accepts a cluster name or ID. Requires project.

List nodes in a Porter cluster with resource capacity, usage, and reservation metrics. Accepts a cluster name or ID. Requires project.

Get full detail for one pod in a Porter cluster the caller can access: owning controller, resource usage, restart count, recent events, Kubernetes metadata, extended status, and spec. Requires project, cluster, namespace, and pod_name.

List pods in a Porter cluster, with status, readiness, restarts, node placement, and resource usage. Accepts a cluster name or ID. Requires project. No namespace or pod-name filtering. Returns truncated=true when capped.

Report how far a Porter cluster has got through provisioning, changing nothing. Provisioning can take up to an hour: poll until status is completed or failed, and do other work between polls rather than waiting on this call. Nothing can be deployed to the cluster until this reports completed. Accepts a cluster name or ID. Requires project.

List clusters in a Porter project. Accepts a project ID or exact name.

Return one job run's status by its exact run name. Accepts an app name or UUID. Requires project. Searches the job's most recent 100 runs; job_run_name is the run name returned when the job was triggered. This tool does not return run history or logs; use list_job_runs for history and get_app_logs with its job_run_name filter set to the run name for output.

List load balancers for a Porter cluster. Accepts a cluster name or ID. Requires project.

Get provisioned node-group size over time for a Porter cluster. Fixed-size groups report node count (unit=count); cost-optimized (Karpenter) groups report provisioned CPU cores (unit=cores).

List runtime notification events for a Porter app (newest first), returning up to 20 at a time with cursor pagination. Each notification carries its error code and the service, pod, and container it came from. Accepts an app name or UUID. Requires project. A page can come back empty while nextCursor is still set, so follow the cursor instead of reading an empty page as the end of the history. Does not cover deploy failures or rollbacks, and cannot dismiss notifications.

Return a Porter project's settings: currently whether it can claim a Porter Cloud cluster. Call it when get_clusters returns no clusters for the project. When porter_cloud_enabled is true, ask the user whether to deploy on Porter Cloud and, on yes, call create_app with cluster omitted; when porter_cloud_enabled is false, connect a cloud account and create a cluster instead. Accepts a project ID or exact name.

List projects the caller can access.

Return one sandbox's current state on a Porter cluster that has sandboxes enabled. Use after create_sandbox to poll until phase is running before calling exec_sandbox. Phases are queued, creating, running, succeeded, failed, and terminated. succeeded, failed, and terminated are terminal; termination_reason and exit_code explain why the sandbox ended. Accepts a cluster name or ID. Requires project.

Return whether sandboxes are enabled and ready on a Porter cluster, along with the cluster's sandbox settings: warm pool, egress enforcement, and domains. Use after enable_sandboxes to poll until ready is true; if ready stays false, get_cluster_status shows whether the sandbox node group is still provisioning or has failed. Settings come back empty until ready is true, because the runtime writes its defaults when it installs. Accepts a cluster name or ID. Requires project.

Install the QM addon (Porter's harness for agents to share context and files across an organization) onto a Porter cluster. Use for requests to set up, install, deploy, or try QM. In oidc mode the provider usually needs the callback URL before it issues a client ID: install without client_id, register an app with the returned oidc_callback_url, then set client_id and client_secret with update_addon. Secret values passed here persist in the conversation transcript; say so before asking the user for them. Returns immediately with next_step: poll get_addon_status until status is installed, waiting_for_sso, or failed. Fails if an addon with this name exists on the cluster and never updates one. Call get_addons first, and after a timeout call get_addon_status instead of installing again.

List quota increase requests filed with AWS for a cloud account in a region, with each request's status (pending, approved, denied), desired quota, and creation time. Use to follow up on an insufficient check_aws_cluster_quota result before advising the user to request an increase, so an already-pending request is not duplicated. AWS only: a cloud account on any other provider is an error, because quota increase requests do not exist outside AWS. Accepts a project ID or exact name and a cloud account ID.

List the cloud accounts connected to a Porter project, with each account's provider, the provider's own account ID, and where it sits in the connect flow. Use it to pick the cloud_account_id for create_cluster, check_aws_cluster_quota, and list_aws_quota_requests: only an account with status connected can be provisioned into, so when exactly one is connected use it without asking, and when several are ask the user which. When none are connected, connect one with connect_cloud_account. Accepts a project ID or exact name.

List recent runs for a job service on a Porter app, newest first. Omit job_name to include runs from all job services. Accepts an app name or UUID. Requires project. Results are capped at the requested limit; truncated=true means older runs exist, but this tool cannot page further. Cron-triggered and manually triggered runs both appear. This tool does not trigger, cancel, or wait for job runs.

List sandboxes on a Porter cluster that has sandboxes enabled, newest first, up to 100 per page. Sandboxes that already finished (succeeded, failed, or terminated) stay in the list as history. When truncated is true, request the next page. This tool does not filter. phase and exit_code here come from a periodic snapshot; use get_sandbox for one sandbox's current state and timestamps. Accepts a cluster name or ID. Requires project.

Redeploy an existing Porter app at its current configuration, restarting all services with zero configuration changes and creating a new revision. Calling this tool triggers the redeploy immediately; there is no dry run or confirmation parameter. Deployment runs asynchronously; follow with get_application_status to monitor progress. Use redeploy_application to restart or retry with the current configuration; use update_application to change configuration. A redeploy may pull a newer image for mutable tags such as latest.

Start a run of a job service on an existing Porter app. Calling this tool starts the run immediately; there is no dry run or confirmation parameter. The run proceeds asynchronously; use get_job_run for status and get_app_logs for output. Accepts an app name or UUID. Requires project. The app must have a successful deploy because the run uses its latest successfully deployed revision. Set run by itself, or use entrypoint and args separately or together; run cannot be combined with either. Set allow_concurrent=true when the job refuses because a run is already in flight.

Change the configuration of an installed QM addon and roll the change out. Only the fields given change, and a stored value cannot be cleared, only replaced. Use it to finish oidc sign-in after install_addon (set qm.auth.oidc.client_id and client_secret), to rotate a key, or to add a custom domain. Omit qm.auth.mode to keep the current sign-in provider; setting a different mode switches providers and needs that provider's fields in the same call. Secret values passed here persist in the conversation transcript. Returns immediately: poll get_addon_status until status is installed or failed. Fails if the addon does not exist; install_addon creates one.

Validate or deploy a delta to an existing Porter app. Dry run defaults to true: first validate, confirm the resulting configuration, then call again with dry_run=false to create a revision and deploy. Services are merged by name so omitted fields and services are preserved; use delete_services for explicit removal. Dashboard-only service settings such as node-group assignment, connections, sleep, service mesh, termination grace, metrics scraping, and advanced routing, TLS, or auth are preserved on existing services but cannot be changed. Build configuration updates do not change the GitHub source or trigger its workflow. Changes to CI-managed porter.yaml apps may be overwritten by the next push. Never accepts or returns variables, secrets, or environment groups.

Change sandbox settings on a Porter cluster that has sandboxes enabled: the warm pool of pre-booted sandboxes, and whether egress allowlists are enforced. Only the fields provided change, and at least one is required. warm_pool replaces the existing pool; its total CPU (size times cpu_millicores) must fit the sandbox node group's CPU cap, 20 cores by default. With egress enabled, a sandbox created with allowed_destinations can reach only those plus cluster DNS; sandboxes created without it keep public internet access. Changing egress restarts the sandbox runtime and rebuilds the warm pool; until that rollout finishes, create_sandbox with allowed_destinations is rejected as unavailable, and any sandbox created mid-rollout can terminate with backend_lost, so retry later. Returns the saved settings before the runtime has applied them. Accepts a cluster name or ID. Requires project.