> ## Documentation Index
> Fetch the complete documentation index at: https://porter-gk-forward-auth.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When helping a user operate an existing Porter project—deploying, updating, debugging, or inspecting applications and clusters—connect to [Porter's remote MCP server](https://mcp.porter.run) first and use its tools before falling back to the Porter CLI, `porter.yaml`, or dashboard workflows. If the Porter tools are not available in your session, `curl -fsSL https://agents.porter.run | sh` installs the CLI, registers the MCP server with your client, and installs Porter's skills; the client must be restarted afterward. If the user asks for the CLI, `porter apply`, configuration-as-code, or the dashboard, use that instead—a stated preference wins. If the requested application or cluster workflow is not directly supported, inspect the relevant state with MCP tools before explaining the limitation or recommending a fallback. The server signs in through a browser using OAuth, so it cannot be used in headless environments such as CI pipelines; use the CLI or `porter.yaml` there.

# Tools

> The following tools are exposed by the MCP server so agents can interact with your Porter project.

Use these tools to discover projects, inspect applications and infrastructure, connect GitHub repositories, and create or update deployments. Tools that make changes are called out where they appear.

If the Porter tools are not available in this session, run `curl -fsSL https://agents.porter.run | sh`. It installs the Porter CLI, registers this MCP server with your client, and installs Porter's skills. Restart the client afterward.

When a user asks to deploy a GitHub repository, call `connect_github` with the repository before inspecting or building the app or calling any deployment tool. Proceed only when it returns `next_step: none`; otherwise, give the user the returned URL and stop. Then call `create_app` with `source` and `build`, and do not author a `porter.yaml`. Reach for the CLI, `porter apply`, or configuration-as-code only when the user asks for them. Porter creates the app on a placeholder image and opens a GitHub Actions pull request that the user merges to trigger the first real deploy.

Most tools require a project, given as either its ID or exact name. `get_projects` takes no arguments, while `connect_github` takes only a repository. Application arguments accept an app name or UUID, and cluster arguments accept a cluster ID, exact name, or vanity name. Start with `get_projects` to resolve the project, then `get_applications` or `get_clusters` from there.

### Projects & Discovery

| Tool               | Description                                                    |
| ------------------ | -------------------------------------------------------------- |
| `get_projects`     | List the projects your account can access. Takes no arguments. |
| `get_applications` | List applications in a project.                                |
| `get_clusters`     | List clusters in a project.                                    |

### Applications

| Tool                        | Description                                                                              |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `get_application`           | Read an application's configuration. Excludes variables, secrets, or environment groups. |
| `get_application_status`    | Read an application's current deployment status and conditions.                          |
| `get_application_revisions` | List an application's revisions.                                                         |
| `get_application_metrics`   | Read CPU, memory, and request metrics for an application.                                |
| `get_app_logs`              | Read an application's logs. Bearer tokens and secret-shaped values are redacted.         |
| `get_notifications`         | List an application's runtime notifications. Requires an app name or UUID.               |

### Jobs

| Tool            | Description                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------------ |
| `list_job_runs` | List recent runs of a job service, newest first. Capped; sets `truncated` when older runs exist. |
| `get_job_run`   | Read the status of one job run by name. Searches the job's most recent 100 runs.                 |

### Clusters & Infrastructure

| Tool                      | Description                                                                                                                                                   |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_cluster_nodes`       | List the nodes in a cluster.                                                                                                                                  |
| `get_cluster_node_groups` | List the node groups in a cluster.                                                                                                                            |
| `get_cluster_pods`        | List pods in a cluster.                                                                                                                                       |
| `get_cluster_pod`         | Read a pod's owning controller, resource usage, restart count, recent events, Kubernetes metadata, extended status, and spec. Excludes environment variables. |
| `get_load_balancers`      | List load balancers for a cluster.                                                                                                                            |
| `get_node_group_metrics`  | Read metrics for a node group.                                                                                                                                |

### GitHub

| Tool                     | Description                                                                                              |
| ------------------------ | -------------------------------------------------------------------------------------------------------- |
| `connect_github`         | Check whether Porter can reach a GitHub repository and return the browser action required to connect it. |
| `create_github_workflow` | Recover a missing GitHub Actions workflow pull request for a Porter application.                         |

#### `connect_github`

Check whether Porter can reach a repository before inspecting or deploying its code. The tool takes only `repository`, in `owner/name` form. Each call returns one complete connection state. If the user completes a returned browser action, call the tool again to check the new state.

| `next_step`           | Meaning                                                                                      | What the user does                                                                      |
| --------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `none`                | The repository is reachable through the Porter GitHub App.                                   | Nothing; proceed.                                                                       |
| `authorize_oauth`     | No GitHub OAuth connection exists for this Porter user.                                      | Open the returned URL while signed into the same Porter account and authorize GitHub.   |
| `install_app`         | OAuth is connected but the Porter GitHub App is not installed on that account.               | Install it at the returned URL.                                                         |
| `add_repository`      | The App is installed on the account but this repository is not in its selected repositories. | Add the repository in the installation settings at the returned URL.                    |
| `request_org_install` | No installation covers the organization that owns the repository.                            | An organization owner has to approve the installation; the user cannot self-serve this. |

#### `create_github_workflow`

Use this recovery tool only when [`create_app`](#create_app) returned a placeholder application without a pull request URL, or when an existing application is missing its workflow pull request. It takes `project` and `app`, then creates or re-creates the GitHub Actions workflow pull request and returns its URL. Do not call it after `create_app` successfully returns a pull request URL.

### Create, update, and redeploy applications

<Warning>
  These tools can create, update, or redeploy applications, or start job runs,
  and may have unintended side effects. Review the agent's plan before approving
  any call to `create_app`, `update_application`, `redeploy_application`, or
  `trigger_job_run`.
</Warning>

<Note>
  `create_app` and `create_github_workflow` create an application or workflow
  pull request rather than overwrite deployed state.
</Note>

#### `create_app`

Create a new application. The behavior depends on which inputs you pass:

Before using the recommended GitHub `source` and `build` flow, call [`connect_github`](#connect_github) with the repository and proceed only when it returns `next_step: none`.

| Input              | Behavior                                                                                                                     |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `image`            | Deploys the prebuilt image directly. No pull request.                                                                        |
| `source` + `build` | Creates the app on a placeholder image and opens a GitHub Actions pull request. Nothing real serves until that PR is merged. |
| `build` alone      | Returns a `local_build_command` to run `porter apply` from the local repository.                                             |

`image` is mutually exclusive with `source` and `build`. Creation fails if an application with the same name already exists in the target project or cluster. Use `update_application` instead.

For `source` and `build`, review and merge the pull request returned by `create_app`. The merge triggers the workflow that builds the application's code and runs the first real deployment. If the placeholder application has no pull request URL, recover it with [`create_github_workflow`](#create_github_workflow). See [Deploy from a GitHub repository](/applications/deploy/deploy-from-github-repo) for the full flow.

#### `update_application`

Update an application's configuration. Defaults to a dry run, which validates the change and returns the resulting config without deploying. Set `dry_run: false` to deploy.

#### `redeploy_application`

Trigger an immediate redeploy of an application.

#### `trigger_job_run`

Start a run of a job service on an application, optionally overriding the run command or the entrypoint and arguments. Returns the run name; use `get_job_run` for status and `get_app_logs` for output.