> ## Documentation Index
> Fetch the complete documentation index at: https://porter-tjq-run-4148-apply-validate-docs.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.

# MCP Overview

> Connect AI agents to Porter's MCP server to inspect and manage your apps and clusters.

Porter hosts an MCP server at `https://mcp.porter.run`. Point an MCP client at that URL, sign in, and your agent can do the same things you'd do in the dashboard or the CLI: read logs, check why a deploy failed, change a service, redeploy it.

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 `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. Confirm that the Porter GitHub App is already installed on the repository; the MCP server cannot install it.

You don't need to install or run anything locally. The server runs on Porter's side, so all your client needs is the URL and a browser to sign in.

```
https://mcp.porter.run
```

## Connect your client

### Quick install

Install the Porter CLI and configure agent support — MCP registration and skills — in one command:

```bash theme={null}
curl -fsSL https://agents.porter.run | sh
```

Restart your client afterward. It prompts for browser sign-in the first time it uses a Porter tool, or pass `--login` to sign in during the install instead.

Run inside an agent session, the installer configures that client alone. `--clients=all` covers every client on the machine, `--dry-run` previews, `--uninstall` reverses, and `--help` lists the rest.

Skills go beyond what the individual [tools](/mcp/tools) describe: `porter-deploy` takes a GitHub repository from nothing to a live URL, following the generated workflow pull request through merge.

To register the server on its own, without the CLI or the skills:

```bash theme={null}
# Claude Code
claude mcp add --transport http porter https://mcp.porter.run

# Codex
codex mcp add porter --url https://mcp.porter.run

# OpenCode, prompts for a name, a type, and the URL
opencode mcp add
```

### Client configuration

<Tabs>
  <Tab title="Claude Code">
    1. Add the server:

       ```bash theme={null}
       claude mcp add --transport http porter https://mcp.porter.run
       ```

       Or add it to `.mcp.json` to share it with the project:

       ```json theme={null}
       {
         "mcpServers": {
           "porter": {
             "type": "http",
             "url": "https://mcp.porter.run"
           }
         }
       }
       ```

    2. Start Claude Code and run `/mcp`.

    3. Select **porter** and sign in through the browser.

    For more information, see the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).
  </Tab>

  <Tab title="Codex">
    1. Add the server:

       ```bash theme={null}
       codex mcp add porter --url https://mcp.porter.run
       ```

       Or add it to `~/.codex/config.toml` directly:

       ```toml theme={null}
       [mcp_servers.porter]
       url = "https://mcp.porter.run"
       ```

    2. Sign in:

       ```bash theme={null}
       codex mcp login porter
       ```

    The ChatGPT desktop app, Codex CLI, and IDE extension share this file, so you only do this once.

    For more information, see the [Codex MCP documentation](https://developers.openai.com/codex/extend/mcp).
  </Tab>

  <Tab title="OpenCode">
    1. Run the setup command:

       ```bash theme={null}
       opencode mcp add
       ```

    2. Enter `porter` as the name, choose **remote**, and paste the URL:

       ```
       https://mcp.porter.run
       ```

       Or add it to `opencode.json` directly:

       ```json theme={null}
       {
         "$schema": "https://opencode.ai/config.json",
         "mcp": {
           "porter": {
             "type": "remote",
             "url": "https://mcp.porter.run"
           }
         }
       }
       ```

    3. Sign in:

       ```bash theme={null}
       opencode mcp auth porter
       ```

    OpenCode also starts the sign-in on its own the first time you use a Porter tool.

    For more information, see the [OpenCode MCP documentation](https://opencode.ai/docs/mcp-servers/).
  </Tab>

  <Tab title="Cursor">
    1. Create or edit `.cursor/mcp.json` in your project root:

       ```json theme={null}
       {
         "mcpServers": {
           "porter": {
             "url": "https://mcp.porter.run"
           }
         }
       }
       ```

       Use `~/.cursor/mcp.json` instead to get Porter in every project.

    2. Restart Cursor.

    3. Open **Settings > Tools & MCP**, select **porter**, and click **Connect**.

    For more information, see the [Cursor MCP documentation](https://cursor.com/docs/mcp).
  </Tab>

  <Tab title="Claude Desktop">
    1. Go to **Customize → Connectors**, click **+**, then **Add custom connector**. On Team or Enterprise, an Owner does this from **Organization settings → Connectors**.

    2. Paste the URL:

       ```
       https://mcp.porter.run
       ```

    3. Click **Add** and approve access in the browser.

    Porter then shows up under **Connectors** in the **+** menu of any conversation. On Team or Enterprise, everyone else finds it already listed and clicks **Connect**.

    <Info>
      Claude connects to remote MCP servers from Anthropic's cloud, not from your machine. That's true in the desktop app too.
    </Info>

    For more information, see the [Claude custom connectors documentation](https://support.anthropic.com/en/articles/11175166-about-custom-connectors-remote-mcp-servers).
  </Tab>
</Tabs>

## Capabilities

You ask for things in plain language, so it's easier to think in terms of tasks than tools:

* **[Deploy an app](/applications/deploy/deploy-from-github-repo).** Create an application and get it running without leaving your agent. If you're deploying a pre-built image, the agent can take it all the way. If you're deploying from a GitHub repo, the agent creates the app and opens a pull request with the build workflow, and you merge it to deploy your code. For the complete setup flow, see the [Quickstart](/getting-started/quickstart#step-4:-create-your-first-application).
* **Update an app.** Change services, resources, or domains on an existing app and redeploy. Updates can be validated with a dry run first, so you can see the resulting config before anything deploys.
* **Troubleshoot your app.** Read logs, metrics, and notifications, or check nodes, node groups, pods, and load balancers to find what's broken. From there you can go back to the config that caused it, fix it, and redeploy.
* **Rightsize a service.** Compare requested CPU and memory against what the service actually uses, then adjust the requests.
* **Copy an environment.** Create dev or staging versions of an existing app, or move one to a different cluster.
* **Inspect resources.** List projects, apps, and clusters, or check the status of a deployment.

Some examples:

```text theme={null}
Help me deploy my code to Porter.

Why did my latest deploy fail?

My web service keeps restarting, figure out why and fix it.

Help me reduce cost for my apps.

Create a staging copy of my production web service.
```

The [tools reference](/mcp/tools) has the full list of tools.

## Limitations

OAuth is currently the only auth method, so headless environments like CI pipelines and sandboxed agents are not supported.

## Risks

<Warning>
  MCP tools can perform destructive operations on your applications, including
  creating, updating, and redeploying services. They can directly impact
  production environments and cause downtime to services if not used with care.
</Warning>

The agent authenticates as you and inherits your Porter permissions.

Recommendations:

* **Use non-production environments first.** Validate changes in a dev or staging project before applying them to production.
* **Review the agent's plan before approving it**, particularly for operations that modify production resources.
* **Disable auto-approval against production.** It is reasonable on a test project and unsafe everywhere else.
* **Account for prompt injection.** The agent reads your application logs, notifications, and pull request bodies, all of which can carry attacker-controlled text. The server cannot distinguish injected instructions from your own, so a compromised agent can call `create_app`, `update_application`, or `redeploy_application` and change or restart a running service. Read tools exclude environment variables and secrets, and redact token-shaped values in logs, so the exposure is to your application's configuration and availability rather than its credentials.

## Revoke access

If you installed with the script, one command removes the CLI, the skills, and the server entries:

```bash theme={null}
curl -fsSL https://agents.porter.run | sh -s -- --uninstall
```

It backs up every file it edits to `~/.porter/backups`. OpenCode's config is left alone, so remove the `porter` entry from `opencode.json` yourself.

Otherwise you revoke access per client. Remove the stored credentials, then delete the server entry so it doesn't sign in again later.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp remove porter
    ```
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    codex mcp logout porter
    codex mcp remove porter
    ```

    `logout` clears the stored OAuth credentials and `remove` deletes the server entry.
  </Tab>

  <Tab title="OpenCode">
    ```bash theme={null}
    opencode mcp logout porter
    ```

    That clears the stored OAuth tokens. Also remove the `porter` entry from `opencode.json` to get rid of the server entirely.
  </Tab>

  <Tab title="Cursor">
    Delete the `porter` entry from `.cursor/mcp.json` (or `~/.cursor/mcp.json`) and restart Cursor.
  </Tab>

  <Tab title="Claude Desktop">
    Go to **Customize → Connectors**, click the three dots next to Porter, and choose **Remove**. On Team and Enterprise plans, an Owner has to remove it for the whole organization from **Organization settings → Connectors**.
  </Tab>
</Tabs>