pg_play exposes a local stdio MCP server and six optional Agent Skills. The
MCP server provides the tools; the skills teach an agent the safe workflow for
planning, starting, monitoring, recovering, and interpreting experiments.
Install pg-play and resolve the server to an absolute path:
python -m pip install pg-play
command -v pg-play-mcpIn every example below, replace /absolute/path/to/pg-play-mcp with that path.
Pass the executable directly, without bash -lc or another shell wrapper.
All local references resolve on the MCP server host. Use absolute manifest,
project, credential and output paths in tool calls so the client's working
directory cannot select a different project.
Keep the server's PATH pointed at the same environment's bin directory:
component lookup prefers commands on PATH over executables beside the server's
Python interpreter. An absolute MCP command alone does not prevent a different
globally installed component from being selected.
pg-play 0.6.0 requires Python 3.11+ and installs all eight components, including
maker and logical replication. For source checkouts, use the
development installation. Use component_capabilities
to verify component versions and supported commands before planning work.
For a source checkout, the skills are in src/pg_play/skills/. For an installed
package, run this with the same Python environment that contains pg-play:
python -c 'from importlib.resources import files; print(files("pg_play").joinpath("skills"))'Copy complete skill directories, including references/ and agents/, into
one supported location below. Do not copy only SKILL.md or install duplicate
copies in multiple scopes. Package upgrades do not update copied skills;
refresh them deliberately. The six names and responsibilities are listed in
Agent skills; there is no separate packaged logical
migration skill yet.
Use detached start/status/events operations for long runs. Configuration-fact collection and some planning calls are synchronous; set the client's tool timeout to allow their collection budget (at least 180 seconds for the bounded configuration review). A client timeout does not prove that a mutation stopped.
Official documentation: MCP · Skills
codex mcp add pg_play -- /absolute/path/to/pg-play-mcp
codex mcp listCopy the skill directories to ~/.agents/skills/ for user scope or
.agents/skills/ for repository scope. Use /mcp and /skills in Codex to
verify discovery.
Official documentation: MCP · Skills
claude mcp add --transport stdio --scope user pg_play -- \
/absolute/path/to/pg-play-mcp
claude mcp listUse --scope project instead of --scope user to create a repository-owned
.mcp.json. Copy skills to ~/.claude/skills/ or .claude/skills/. Use
/mcp to verify the server; skills can be invoked as /run-postgres-experiment
and by their other directory names.
Official documentation: MCP · Skills
Add the server to ~/.hermes/config.yaml:
mcp_servers:
pg_play:
command: "/absolute/path/to/pg-play-mcp"
args: []
enabled: trueCopy skills to ~/.hermes/skills/, then restart hermes chat. Keep Hermes'
default sequential MCP execution; do not enable parallel tool calls for this
stateful orchestrator.
Official documentation: MCP · Skills
Create ~/.kimi-code/mcp.json, or .kimi-code/mcp.json for one repository:
{
"mcpServers": {
"pg_play": {
"command": "/absolute/path/to/pg-play-mcp",
"args": [],
"startupTimeoutMs": 20000,
"toolTimeoutMs": 180000
}
}
}Copy skills to ~/.agents/skills/, ~/.kimi-code/skills/, or their project
equivalents. Use /mcp to verify the server and /skill:<name> to invoke a
skill explicitly.
Official documentation: MCP · Skills
Add this to ~/.gemini/settings.json, or .gemini/settings.json in a project:
{
"mcpServers": {
"pg_play": {
"command": "/absolute/path/to/pg-play-mcp",
"args": []
}
}
}Copy skills to ~/.agents/skills/, ~/.gemini/skills/, or their project
equivalents. Use /mcp list and /skills list; use /skills reload after
changing skill files.
Official documentation: MCP · Skills
Add this to the project opencode.json or the user configuration:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"pg_play": {
"type": "local",
"command": ["/absolute/path/to/pg-play-mcp"],
"enabled": true
}
}
}Copy skills to ~/.agents/skills/, ~/.config/opencode/skills/, or their
project equivalents. Run opencode mcp list to verify the connection.
Use the pg_play MCP tools and the matching pg_play skill. Validate and plan
before starting any mutation. Show me the plan and ask for missing access or
tuning inputs. Use detached start operations and monitor status and events.
pg-play-mcp currently uses stdio only. The client must therefore run on a host
where the executable, Docker access, SSH identities, manifests, and report
paths are available. When target.ssh.auth is agent, start the MCP server
from an environment with a live SSH_AUTH_SOCK; detached diagnostic workers
inherit that socket path, so the agent must outlive the capture. A hosted agent
needs a separately secured remote MCP transport.