Working with AI Agents

You can let an AI agent run the pgedge CLI, and you can use the CLI to give an agent query access to a database. These are two separate jobs:

• Driving the CLI: the agent runs pgedge commands and reads the results. It needs an accurate description of the CLI to do this.
• Querying a database: pgedge deploys pgEdge's own MCP server beside a database. The MCP server gives the agent a query interface over that database. The CLI takes part only at deploy time.

Both jobs apply to the two editions of pgEdge Starfleet, pgEdge Starfleet Managed and pgEdge Starfleet BYOC, and to the self-hosted Control Plane.

Letting an Agent Drive the CLI

An agent that builds commands from --help output is guessing. The CLI ships two things that give the agent an exact description: a machine-readable reference inside the binary, and a set of agent skills.

Reading the Built-In Reference

pgedge llms prints the index. The index covers what holds across the whole CLI:

• global flags
• configuration and profiles
• environment variables
• output formats and exit codes

Its tables route to each module's own reference. They also route to a page per top-level command group, such as pgedge llms inspect. Point an agent at the index first, because the index tells the agent which read it needs next.

pgedge llms <module> prints one module's index. The index covers what holds across the module, then a Pages table routes to one page per resource. A page's path is its command's path: for example, pgedge llms starfleet byoc cluster documents pgedge starfleet byoc cluster and its commands.

The database page routes once more, to its sub-resources, such as pgedge llms starfleet managed database mcp. The starfleet module carries two product sub-trees, byoc and managed, and each has an index of its own. An agent reaches any command in three short reads. A sub-resource of a product sub-tree takes four. At each step the agent loads only the resource it is working on.

The whole reference ships inside the binary. An installed copy prints it offline, with the binary alone. If you name a module the binary does not carry, the command fails with exit status 2. The message lists the modules the binary does carry.

The same content is on this site in the pgedge command reference, generated from the same command tree. An agent with a terminal should use pgedge llms, because it describes the binary that is installed.

Installing the Agent Skills

pgEdge ships five agent skills, one for orientation and one for each product area. They follow the Agent Skills open standard. One command installs them for your user and detects your agent:

npx skills add pgEdge/pgedge-cli --global

Installing the Agent Skills covers the Claude Code and Codex plugins, pinning the skills to a release, and copying them by hand.

Parsing Command Output

-o json and -o yaml render the API's own object. The renderer passes both through the same JSON tags, so a yq path always matches the equivalent jq path. --verbose and --debug write their diagnostics to stderr, so stdout carries only the result.

Some successes return an empty stdout in all three formats. For these, the acknowledgment is exit status 0 and a sentence on stderr. An agent that reads an empty stdout as failure misreads them, so judge success by the exit status. The Output formats and paging page has the full contract. The Exit codes page covers what each status lets an agent conclude.

Deploying an MCP Server

The MCP server runs beside a Postgres database and gives an LLM a query interface over it. The server is read-only unless you grant more. The commands that deploy one depend on the product, and each of the three below has its own recipe.

Deploying on a Managed Database

The write commands live under database mcp. A deploy with no flags set yields a read-only server with an API-generated bearer token:

pgedge starfleet managed database mcp deploy <database-id> --wait

If an MCP service is already deployed, deploy refuses to run and names mcp update as the fix. The Deploy managed services page covers every configuration flag. It also says which flags the API treats as secrets, and exactly what a wait proves.

Deploying on a BYOC Database

The commands read the same. The service runs on the cluster's own nodes in your cloud account, so your own networking stands in front of its endpoint:

pgedge starfleet byoc database mcp deploy <database-id> --wait

On a multi-node cluster, pass --target-nodes, because the CLI refuses to choose the placement. The Deploy BYOC services page covers placement and the configuration flags. It also covers the regional ingress a private cluster needs before anything outside the VPC can reach the service.

Deploying on a Self-Hosted Control Plane

The Control Plane has no mcp command group. Declare the service in the database spec instead, under the spec's services block. The service reaches the Control Plane when you create the database:

pgedge controlplane database init -i > storefront.yaml
pgedge controlplane database create storefront -f storefront.yaml --wait

database init -i interviews you for the spec. Its guided services step collects these values:

• the service type
• a service id
• the connect-as database user
• host IDs and version
• a guided LLM configuration, for an mcp service

The interview writes every credential as a placeholder. The provider credential lands as CHANGE-ME, and create refuses the spec until you replace it. The Manage Control Plane databases page covers the three service shapes. It also covers the bootstrap credentials the Control Plane accepts on create and rejects on update.

Connecting an Agent to a Deployed Server

On the Control Plane, you configure a service through the spec's config block, and its init token field holds the bearer token. The Manage Control Plane databases page covers reading a service back.

On Managed and BYOC, an MCP client needs two values. Both come from a read of a single database, so take neither from the deploy output.

The endpoint is the first value, and the two products report it in different ways. The following table shows where each one leaves it:

Take that value from the API, because the platform chooses the path segment. On Managed, service list, service get and database get all print it as ENDPOINT, and -o json carries the field itself. On BYOC, the CLI builds ENDPOINT for the table from the service's domains. Under -o json, a script builds the same locator from the raw fields.

The bearer token is the second value. It holds one of three things:

• the value passed to --init-tokens at deploy time
• a token the API generated, when the deploy omitted that flag
• a token rotated afterward with mcp update

A token typed as a flag lands in your shell history. Anyone on the same host can also see it in ps. Let the API generate the token instead, and read it back.

Table views leave out every secret, in any format. Read the token with -o json on a read that hits the single database. database get, service get and service list all carry it, and database list leaves it out. The token sits in the services entry whose service_type is mcp, under that entry's mcp_config block.

On Managed, mcp connection prints both values and nothing else from the database. It exits with status 1 when the database has no MCP service or no token, so a script stops on its exit status. The following script reads both values for a managed database:

mcp=$(pgedge starfleet managed database mcp connection \
    <database-id> -o json)
rc=$?
if [ "$rc" -ne 0 ]; then
    exit "$rc"
fi
uri=$(printf '%s' "$mcp" | jq -r .uri)
token=$(printf '%s' "$mcp" | jq -r .token)

The values stay in shell variables, so no file holds the token. Run the command again each time, instead of keeping the values for a later session.

Configuring the MCP Client

Each agent keeps its MCP client configuration in its own place, and its own documentation names that place. Every agent's configuration holds the same two entries:

• the URL from the table above, as a streamable-HTTP MCP server.
• an Authorization header carrying Bearer and the token.

The transport wants an Accept header naming both JSON and the event stream. The first request on a connection must be an initialize call. A tools/list sent first is a lifecycle violation. A client that speaks streamable HTTP handles both of these itself. A server may answer with an Mcp-Session-Id header, which later requests on the same session echo back.

Checking Readiness After a Deploy

Exit status 0 on a deploy means the API accepted the write. The server may still be unable to answer. On Managed, the endpoint returns 503 for a while after the deploy. During that window, the service state field already reads running.

A successful initialize call is the true readiness signal. Both services pages carry a curl recipe that makes one. Point the agent at the server when that call succeeds, and ignore the deploy's return.

Setting Query Limits and Write Access

Managed and BYOC deploy the same server, and it behaves as follows.

The query tool takes a limit and an offset to continue from. The limit defaults to 100 rows and tops out at 1000. The server appends both to a query that lacks them. A truncated response says more rows are available, and names the offset to continue from. A complete result of the same size reports only its row count.

All of that depends on the server supplying the limit. The server checks for an existing limit with a substring test over the query text. Any LIMIT in the text stops the server appending anything, and turns off the truncation notice with it. A column name or an alias such as unlimited counts. An agent should pass limit as a parameter, and keep the clause out of the SQL.

Write access is off by default. On Managed and BYOC, --allow-writes grants the LLM insert, update and delete access through the query tool.

Next Steps

These pages cover the next tasks:

• The Deploy managed services page covers deploying and configuring an MCP server on a managed database.
• The Deploy BYOC services page covers the same on a BYOC database. Enough differs there that a Managed recipe needs changes before it works.
• The Manage Control Plane databases page covers declaring services in a Control Plane database spec.
• The Getting started page covers installing the CLI and its skills from scratch.