Agents and MCP
Coding agents should not wait on humans to provision databases. Point a harness at Portside once; every future session can stand up, use, and wipe its own isolated instances.
Two paths lead here. Harnesses with MCP support (opencode, Claude Code, Codex, Cursor, Windsurf, pi, omp) get structured tools via portside-cli mcp. Anything else - shell-only agents, scripts, CI - uses the Headless CLI directly. Both drive the same core, so an instance created over MCP appears in the CLI and the desktop GUI alike.
One-command harness setup
portside-cli setup-agent --host <name> registers the MCP server in that harness's config file, merging into the existing file without touching anything else. Reruns are idempotent ("already configured"). An existing-but-invalid file is refused, never overwritten. Default scope is user-global; add --project-dir <dir> for project-scoped files. Installer users without the repo get the same buttons in the desktop app's Agents panel.
--host | User-global file | Project file |
|---|---|---|
opencode | OS config dir opencode/opencode.json | ./opencode.json |
claude | ~/.claude.json | .mcp.json |
codex | ~/.codex/config.toml (appends [mcp_servers.portside], rest untouched) | .codex/config.toml |
cursor | ~/.cursor/mcp.json | .cursor/mcp.json |
windsurf | ~/.codeium/windsurf/mcp_config.json | .windsurf/mcp_config.json |
pi | ~/.pi/agent/mcp.json | .pi/mcp.json |
omp | ~/.omp/agent/mcp.json | .omp/mcp.json |
generic | Prints a paste-block to stdout, writes nothing | - |
portside-cli setup-agent --host cursor
# wrote MCP config (existing entries preserved)
# /home/alice/.cursor/mcp.json
Notes: omp also discovers other tools' configs natively, so an opencode/Cursor/Claude entry often lights up omp sessions with no extra step. pi users may alternatively run pi mcp add portside -- <path-to-portside-cli> mcp.
The MCP tools
portside-cli mcp serves 11 tools over newline-delimited JSON-RPC on stdio. Failures come back as tool errors (isError: true), never protocol errors, so hosts surface them inline.
| Tool | Purpose | Key arguments |
|---|---|---|
list_instances | List instances | - |
list_catalog | Available engine versions | - |
create_instance | Create an instance, wait until healthy, return connect URLs | engine (required), tag, port (0 = auto), lan, password, wait (default 60s) |
get_connection | Connect strings for one instance | id, lan, strict |
create_database | CREATE DATABASE (SQL engines) | id, name |
list_databases | Databases in one instance | id |
instance_health | Container/tcp/query health | id, wait |
container_logs | Tail container logs | id, tail |
start_instance / stop_instance | Lifecycle | id |
remove_instance | Drop container; wipe: true drops the volume too | id, wipe |
create_instance returns id, engine, tag, port, status, localhost_url, lan_url, and tls in one call - the orchestrator hands the URL to whatever needs it and never touches Docker itself.
PATH management
Harness configs should invoke portside-cli by bare name when it resolves on PATH (survives reinstalls to other directories); setup-agent does this automatically and falls back to the absolute binary path otherwise. The Tauri installer does not touch PATH, so:
portside-cli setup-path # add this binary's directory to the user PATH
portside-cli setup-path --remove # undo (same toggle lives in the Agents panel)
Windows edits the user (HKCU) PATH with no elevation; macOS/Linux link into ~/.local/bin with no sudo. Restart terminals and agent harnesses after changing PATH - running processes keep the old environment.
Prompt recipes
Once a harness is registered, these prompts just work:
Use portside to stand up postgres 17 with a database called demo
and give me the connect string.
My experiment is done - wipe every stopped portside instance
but leave the running ones alone.
Stand up redis 8 on its default port and show me the health check.
Remote agents: the LAN handoff
An agent on another machine cannot drive local Docker, but it can use a local database. The local orchestrator creates with --lan (binds all interfaces, serves TLS with a self-signed cert) and hands over the lan_url:
portside-cli create --engine postgres --tag 17 --lan --wait 60 --json
portside-cli conn <id> --lan --json # lan_url for the remote agent
Default posture is encryption without verification (pgAdmin-style); pass --strict for verify-ca mode, which requires downloading the instance's certificate (the row's Cert button in the GUI). Details and the trust tradeoffs live on the Networking and TLS page.
Security notes
- Passwords are set once at creation and stored plaintext in the local SQLite metadata DB - same exposure as the connect strings the GUI already copies to clipboards. Treat the dev box accordingly.
- Localhost instances are plaintext by design (loopback only); only LAN-bound instances serve TLS.
- LAN URLs, TLS certs, and passwords are connection secrets: they belong in the structured tool result or the local
.env, never pasted into shared chats or committed files.