All jobs

How Much Neon Did Each Client Use Last Month? A Software Agency's Usage Report for Invoices

A software agency's agent reads last month's Neon consumption for every client project and writes the usage table its bookkeeper prices on each client invoice.

Run this on RushOpens the console with this prompt ready to send. Connect Neon there first.

What the agent does

This is for a software agency that builds and runs web apps for its clients and keeps each client's database as its own Neon project, inside the agency's Neon organization. Neon bills the agency once a month for the whole organization; the agency passes database costs on to each client at its own rates, which means someone opens the Neon console at month end and copies numbers project by project into a spreadsheet. The agent does that reading. Someone at the agency connects Neon once with POST /me/connections {"type": "mcp", "name": "neon", "url": "https://mcp.neon.tech/mcp", "auth": {"mode": "oauth"}} and, on Neon's consent page, picks read-only access and all projects. In read-only mode Neon's server removes every tool that changes something, such as create_branch and delete_branch, and also get_connection_string, whose string carries a privileged role password.

The run calls list_organizations to find the agency's organization id, then list_projects with that org_id to get every project's id and name. It calls get_project_consumption once with granularity set to monthly, from and to covering last month, and the metrics the agency bills on: compute_unit_seconds, root_branch_bytes_month, child_branch_bytes_month, public_network_transfer_bytes, extra_branches_month and snapshot_storage_bytes_month. It leaves project_ids out, which Neon reads as every project with history in the organization, deleted ones included, so a client whose project was removed mid-month still gets billed for the days it ran.

Each project is assigned to a client by the naming rule in the prompt (client-<name>, for example). A project that does not follow the rule goes into an unassigned list rather than being guessed into someone's invoice. The agent converts compute-unit seconds to compute-unit hours and byte-months to GB-months for reading, and keeps Neon's raw figures beside them so the bookkeeper can check a conversion.

For any client project whose child_branch_bytes_month is above zero, the agent calls list_branches sorted by updated_at and lists the non-default branches nobody has touched in 30 days: preview and test branches that keep adding storage after the work they were made for has shipped. It reports them; it does not delete them. It never calls run_sql, so it reads Neon's usage records and branch metadata, not a single row of any client's data.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Report Neon usage from 2026-10-01T00:00:00Z to 2026-11-01T00:00:00Z. Call list_organizations, then list_projects with that org_id. Call get_project_consumption with granularity monthly, that from and to, the org_id, and metrics compute_unit_seconds, root_branch_bytes_month, child_branch_bytes_month, public_network_transfer_bytes, extra_branches_month and snapshot_storage_bytes_month. Leave project_ids out so deleted projects with usage are included. A project named client-<name> belongs to client <name>; put every other project under unassigned. Convert compute_unit_seconds to compute-unit hours and each byte-month metric to GB-months, keeping the raw values. For each client project with child_branch_bytes_month above zero, call list_branches sorted by updated_at and list its non-default branches not updated since 2026-10-02. Write usage.csv (client, project_id, project_name, deleted, each metric raw and converted) and usage.md (a table per client, the unassigned projects, the stale branches). If a tool answers 403, stop and report Neon's message. Do not call run_sql, and put no prices or rates in either file.",
  "connections": [
    "neon"
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

Two files come back as artifacts on the session: usage.csv, one row per project with its client, and usage.md, the same numbers grouped by client with the unassigned projects and the stale branches at the end. The session's result is a short summary for whoever started it. The bookkeeper opens the CSV next to the agency's rate card and prices each client's line in the accounting tool; the agent never sees the rates.

Before anything goes on an invoice, a person checks three things. The unassigned list, because a project named by a new developer who did not know the rule belongs to someone. Deleted projects, because the client may already have been told their database was gone. And the organization total against the invoice Neon sent the agency, since that invoice is what the agency actually pays.

The stale branch list goes to the developer who owns each client. A branch kept on purpose, such as a copy taken before a risky migration, stays; the rest they delete in Neon themselves.

Run it on every month end

In the console, a Project automation with a schedule trigger (0 7 1 * * in the agency's timezone) can run a saved agent that names the Neon connection and holds the naming rule and the file layout, with a prompt that asks for the previous calendar month. Its notify_each_run setting decides whether the result reaches the person who set it up on its own or in the day's Slack message.

An agency that runs its billing from its own script can send this request from there instead, on the first of the month, with a request_id that is a UUID v5 of the month, so a script that retries starts one run, not two.

The use case this job follows, with its automation and trigger: Produce a report or file, no repo.

Why run it on Rush?

The report itself is not hard; it is tedious and easy to get wrong by one row, and it lands on the same person every month. The agent reads the same consumption call each time, applies the same naming rule, and puts anything that does not fit in front of a person instead of guessing. Neon's sign-in stays in Rush's connection with read-only access chosen on Neon's own page, not an organization API key copied into a billing script on a laptop.

Each run has its own computer and a record of every tool call it made and what it cost, so when a client questions a number the agency can show which call returned it. A new client is a new project with the right name; nothing in the request changes.

Frequently asked questions

Does the agent read our clients' data?

No. It reads Neon's consumption figures and project and branch records, and the prompt forbids run_sql. Neon's own docs advise against connecting MCP agents to production databases; this job never queries a database, and read-only access removes the tools that could change one.

What if our Neon plan does not include consumption metrics?

Neon serves get_project_consumption on its Launch, Scale, Agent, Business and Enterprise plans and answers 403 on others. The prompt tells the agent to stop and report Neon's message, so a month with no data never turns into an invoice with zeros.

A client has more than one Neon project. Does that work?

Yes, as long as each project's name follows the rule, such as client-acme-prod and client-acme-staging with the rule changed to match. Both rows land under the same client in usage.md, and the CSV keeps them apart so the agency can bill staging at a different rate.

Could it create the invoices too?

Rush lists QuickBooks, so a second step could draft invoices there from the CSV. This page stops at the usage file on purpose: the rates and the decision to bill are the agency's, and a person enters them.

More Neon jobs

More jobs like this: Produce a report or file, no repo

Keep reading