# AI agents

> Install Porticol, put porticol-cli on your PATH, sign in once, and connect Claude Code, Cursor, Codex or VS Code over MCP.

Canonical: https://porticol.app/docs/ai-agents

[View as Markdown](https://porticol.app/docs/ai-agents.md)

Porticol's MCP server runs on your machine through `porticol-cli mcp`. It serves the workspace the desktop app keeps: your collections, environments and history. Secrets are resolved inside Porticol and masked in every tool result; sends to a protected environment wait for a person in the app.

This page is the full setup path: app, command line and agent client.

## 1. Install the app and the command line

On macOS or Linux:

```sh
curl -fsSL https://porticol.app/install.sh | sh
```

On Windows, in PowerShell:

```powershell
irm https://porticol.app/install.ps1 | iex
```

The script installs Porticol and `porticol-cli`. On a Mac without Homebrew it often puts the CLI in `~/.local/bin`, which is not on your `PATH` by default. When the script prints a line to add it, run that line, then open a new terminal.

Check both pieces:

```sh
porticol-cli version
```

Open Porticol from Applications (macOS), the applications menu (Linux) or the Start menu (Windows). See [Getting started](https://porticol.app/docs/getting-started) for Homebrew, archives and `--no-cli`.

## 2. Sign in once in the app

The first launch asks for a free account (or your team server). Signing in uploads nothing; your collections stay on this computer. After that the app works offline and checks the account at least every 30 days.

Import from Postman on the sign-in screen if you are moving collections across.

`porticol-cli mcp` reads the desktop workspace and keychain secrets. You do not run `porticol-cli login` for local MCP unless you also use the CLI against a server workspace in CI; see [MCP server](https://porticol.app/docs/mcp) and [Command line](https://porticol.app/docs/cli).

## 3. Connect your agent client

Each client starts the same server: `porticol-cli mcp`, read-only unless you add `--write`.

**Claude Code**

```sh
claude mcp add porticol -- porticol-cli mcp
```

**Cursor** — `~/.cursor/mcp.json` (or `%USERPROFILE%\.cursor\mcp.json` on Windows):

```json
{
  "mcpServers": {
    "porticol": {
      "type": "stdio",
      "command": "porticol-cli",
      "args": ["mcp"]
    }
  }
}
```

**Codex** — `~/.codex/config.toml`:

```toml
[mcp_servers.porticol]
command = "porticol-cli"
args = ["mcp"]
```

**VS Code** — `.vscode/mcp.json` in the folder you open:

```json
{
  "servers": {
    "porticol": {
      "type": "stdio",
      "command": "porticol-cli",
      "args": ["mcp"]
    }
  }
}
```

Restart the client or reload MCP after you edit a config file. To let an agent create or change requests, use `porticol-cli mcp --write` in the command above.

## 4. Check that it works

In the agent, ask it to list environments or search your workspace, for example: "Search my Porticol workspace for checkout". It should call `search` or `environments` and return names without secret values in the clear.

If the client says `porticol-cli` was not found, fix your `PATH` and try again. If tools fail with an empty workspace, open Porticol, confirm you are signed in and that collections exist, then retry.

## 5. CI and remote workspaces

Agents on your machine use the local workspace. In CI, `porticol-cli run` uses files or `--server` with `PORTICOL_TOKEN`; that path does not replace local MCP beside the desktop. See [Automation](https://porticol.app/docs/automation) and [Moving from Postman](https://porticol.app/docs/moving-from-postman).

## Reference

- [MCP server](https://porticol.app/docs/mcp): tools, scopes, protected environments and streamable HTTP on a server
- [Agent skill](https://porticol.app/SKILL.md): short instructions coding agents load from the site
- [Command line](https://porticol.app/docs/cli): `run`, `login` and exit codes