---
name: porticol
description: Use Porticol, a native API client and Postman alternative, to search, read, send and run a team's API collections over MCP, and to run them in CI with porticol-cli.
---

# Porticol

Porticol is a desktop API client for macOS, Windows and Linux. Its command line,
`porticol-cli`, runs collections in CI and serves the user's workspace to coding agents
over MCP. Use it when the user asks you to call, debug or test an API they keep in
Porticol or in a Postman export.

Full setup for app, CLI and agents: https://porticol.app/docs/ai-agents.md

## Setup

Run these steps in order when Porticol is not ready on the user's machine.

### 1. Command line

Check: `porticol-cli version`. If it is missing, install it.

```sh
# macOS or Linux x64, with the desktop app
curl -fsSL https://porticol.app/install.sh | sh
```

```powershell
# Windows x64, in PowerShell, with the desktop app
irm https://porticol.app/install.ps1 | iex
```

If the install script prints a `PATH` line (common on macOS when it uses
`~/.local/bin`), run that line and open a new shell.

For the command line alone, take the archive for the machine from
https://porticol.app/download#cli and put `porticol-cli` on the `PATH`.

### 2. Desktop app

Open Porticol after install, or install from https://porticol.app/download if the user
only needs the app. The first launch asks for a free account; signing in uploads nothing.
Local MCP reads this workspace and the keychain secrets the app created.

### 3. Agent client

Add the MCP server. It starts with `porticol-cli mcp`, read-only.

Claude Code:

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

Cursor, in `~/.cursor/mcp.json`:

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

Codex, in `~/.codex/config.toml`:

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

VS Code, in `.vscode/mcp.json`:

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

Add `--write` after `mcp` only when the user wants you to create or change requests.

### 4. Verify

Call `environments` or `search` on the workspace. If the CLI is missing, fix `PATH`. If
the workspace is empty, the user should open Porticol and import or create collections.

## Accounts

Running a collection in CI needs a Porticol account, free for one seat. On the user's
machine, `porticol-cli login` opens the browser to sign in. In CI, pass an API token
from the account portal as `PORTICOL_TOKEN`. `mcp`, `lint` and `diff` need no sign-in
for local use beside the desktop workspace.

## Tools

| Tool | What it does |
| --- | --- |
| `search` | Search collections, requests and history for a query |
| `read` | Read a collection with its requests and examples, or one request |
| `environments` | List the environments, or read one |
| `send` | Send a request and return what came back |
| `run` | Run a collection and wait for it; a long run comes back still going |
| `history` | List recent sends, or read one |
| `import_openapi` | Preview an OpenAPI document as a collection, without importing it |
| `create_request` | Add a request or folder (write) |
| `update_request` | Replace what a request or folder holds (write) |

Work from what is there: `search` before you guess a request's name, `read` before
you send, and `run` a collection rather than sending its requests one by one.

## Rules

- Secret values come back masked. Never ask the user to paste a secret; it is resolved
  inside Porticol.
- A send to a protected environment answers `needs_confirmation`. Tell the user what you
  want to send and why, wait for them to allow it in Porticol, then call `send` again.
  Never retry in a loop.
- `import_openapi` only previews. Importing is the user's decision.
- Every send you make is recorded in history under your client's name.

## In CI

```sh
porticol-cli run checkout.json -e staging.json --secret apiKey -r junit:report.xml
```

`--secret apiKey` reads the value from the `apiKey` environment variable. Exit code 0
means every request, assertion and threshold passed; 1 means a test or threshold
failed; 2 means a request could not be made; 3 means the command line, a file, the
configuration, the token or a variable is wrong; 4 means the licence refused the run.
The rest are in https://porticol.app/docs/cli.md. A Postman collection export runs as
it is.

## More

- Setup (app, CLI, agents): https://porticol.app/docs/ai-agents.md
- MCP reference: https://porticol.app/docs/mcp.md
- Command line: https://porticol.app/docs/cli.md
- Moving from Postman: https://porticol.app/docs/moving-from-postman.md
- Every page, for agents: https://porticol.app/llms.txt