Skip to content

Latest commit

 

History

History
181 lines (140 loc) · 6.17 KB

agent-client-setup.md

File metadata and controls

181 lines (140 loc) · 6.17 KB

Connect pg_play to agent clients

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.

Prerequisites

Install pg-play and resolve the server to an absolute path:

python -m pip install pg-play
command -v pg-play-mcp

In 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.

Codex CLI

Official documentation: MCP · Skills

codex mcp add pg_play -- /absolute/path/to/pg-play-mcp
codex mcp list

Copy the skill directories to ~/.agents/skills/ for user scope or .agents/skills/ for repository scope. Use /mcp and /skills in Codex to verify discovery.

Claude Code

Official documentation: MCP · Skills

claude mcp add --transport stdio --scope user pg_play -- \
  /absolute/path/to/pg-play-mcp
claude mcp list

Use --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.

Hermes Agent

Official documentation: MCP · Skills

Add the server to ~/.hermes/config.yaml:

mcp_servers:
  pg_play:
    command: "/absolute/path/to/pg-play-mcp"
    args: []
    enabled: true

Copy skills to ~/.hermes/skills/, then restart hermes chat. Keep Hermes' default sequential MCP execution; do not enable parallel tool calls for this stateful orchestrator.

Kimi Code CLI

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.

Gemini CLI

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.

OpenCode

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.

Recommended first prompt

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.