Download
View as Markdown

AI agents

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. Porticol Guard checks every send and run against one policy, and a risky call waits 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:

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

On Windows, in 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:

porticol-cli version

Open Porticol from Applications (macOS), the applications menu (Linux) or the Start menu (Windows). See Getting started for Homebrew, archives and --no-cli.

2. Open the app, no account

Porticol opens into the workbench with no account and no sign-in. Local use, including porticol-cli mcp, needs none. An account is first asked for at an invite, a sync, a share, a team gateway, a CI token against cloud collections, or a purchase.

Signing in uploads nothing; your collections stay on this computer. A managed device whose policy requires your organisation's server still starts at sign-in.

Import from Postman on the start 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 and Command line.

3. Connect your agent client

Open the start screen and choose Connect my coding agent. Porticol finds Claude Code, Cursor and Codex on the computer, shows the exact lines it will add to each one's settings, and writes nothing until you click Add Porticol. Remove restores the file.

The same screen adds Guard's setup where each agent allows it:

  • Claude Code (macOS and Linux): the sandbox on, its network through Guard's local proxy, writes to the data folder denied, credential files such as .env* and ~/.aws closed to reads, and a PreToolUse HTTP hook on Bash.
  • Codex: [features.network_proxy] on and the proxy variables in shell_environment_policy.set, both in ~/.codex/config.toml, and a PreToolUse command hook in ~/.codex/hooks.json.
  • Cursor: beforeShellExecution and beforeMCPExecution hooks in ~/.cursor/hooks.json, with failClosed: true. Cursor has no setting that forces its traffic through a proxy.

Runtimes that use Guard's proxy need its certificate: porticol-cli agent setup --print-trust prints the variables that make Node, Python, curl and other runtimes trust it and send through the proxy, plus the Java keytool line.

By hand, each client starts the same server: porticol-cli mcp, which serves the workspace's tools, including the ones that write. Add --read-only if the agent should read without changing anything.

Claude Code

claude mcp add --scope user porticol -- porticol-cli mcp

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

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

Codex — ~/.codex/config.toml:

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

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

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

Restart the client or reload MCP after you edit a config file. To serve the read tools alone, use porticol-cli mcp --read-only 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.

The same server lists the workspace as resources (porticol://workspace/...) and the built-in prompts (run-collection, debug-request, import-openapi), so a client that supports them can read context and start a workflow without a tool call.

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 that collections exist, then retry.

5. Guard and approvals

Porticol Guard applies one policy to every agent call. The three levels are guided (MCP), enforced (the local proxy) and gated (the team gateway, on Business). The Guard page states what each one stops and what it does not, with the policy schema.

The level 2 setup depends on the agent: Claude Code's sandbox sends its shell network through Guard's proxy; Codex gets the proxy settings and a deny-only hook; Cursor gets its hooks, with no forced network path. Windows runs levels 1 and 3 only.

When a send or run needs a person, it returns:

{
  "status": "pending",
  "approval_id": "8f0c…",
  "reason": "DELETE to production needs a person.",
  "message": "A person must approve this call in Porticol. Call send again with the same request and approval_id once they have. Do not loop and do not ask for a secret."
}

The reason is the default on a protected environment; a rule can carry its own. Approve the exact request in the app's approval card, or with porticol-cli approve <id> and the four-letter code shown on the card. The approval is bound to a SHA-256 of the request the policy decided: the method, URL, environment, headers, auth, protocol, settings and body. A call through the local proxy binds the method, URL, environment, headers and body the proxy saw. It is single use and expires after 10 minutes. The agent retries once with the same request and approval_id. A denied call returns {"status": "denied"} and is not retried. Tell the agent never to loop and never to ask for a secret.

6. 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 and Moving from Postman.

Official MCP Registry

Porticol is listed in the official MCP Registry as app.porticol/porticol-mcp. Install and connect with the steps above; the registry entry points here for setup. Clients that install from the registry still need porticol-cli on your PATH from the install script or the CLI archives.

Reference