Mattering Automations Neon integration
Connect Neon to Mattering Automations: projects with connection strings, database branches, compute endpoint lifecycle, per-branch databases and roles, async operation polling, and consumption metrics as workflow steps, authenticated with one Neon API key.
The Mattering Automations Neon integration adds the Neon API v2, the management surface of Neon's serverless Postgres platform, to your automation canvas: list and manage projects and fetch ready-to-use connection strings, create and delete database branches with copy-on-write forks of your data, run the compute endpoint lifecycle including start, suspend, and restart, manage the databases and roles that live on each branch, poll the asynchronous operations Neon schedules for its writes, and pull consumption metrics for cost reporting.
The credential is a Neon API key sent as a Bearer header. Any Neon user can create a personal key, organization admins can create organization keys and project-scoped keys, and all three variants work with this integration. Setup takes a few minutes once the key exists, and this guide walks through each step, including the asynchronous operations model that most Neon writes follow, and ends with the full node reference.
The safety modeling is stated on the nodes rather than buried. Of the 39 nodes, 20 read and 19 act, and five carry a destructive flag: Neon: Delete Project, Neon: Delete Branch, Neon: Delete Compute Endpoint, Neon: Delete Database, and Neon: Delete Role. Some surfaces are deliberately absent: API key creation and revocation stay in the Neon Console because minting credentials from a credential is self-escalation, the endpoint that reveals a role's stored password is omitted in favor of the safer password reset, and Neon's restore and snapshot operations are not shipped.
Before you start
- A Neon account. The Free plan covers the core surface end to end: projects, branches, compute endpoints, databases, roles, connection strings, and operations all work without a paid plan.
- The ability to create an API key. Any user can create a personal key from account settings; organization keys and project-scoped keys are created by organization admins. A project-scoped key is the natural fit for an automation that should only ever touch one project.
- For the consumption metrics nodes, an account on the plans Neon's API spec names: the current per-project node serves accounts on Launch, Scale, Agent, Business, and Enterprise plans, the per-branch node serves accounts on paid usage-based Launch, Scale, Agent, and Enterprise plans, and the legacy node serves Scale, Business, and Enterprise plan projects. You will also need your organization ID, which Neon: List My Organizations returns.
- A Mattering workspace with access to the Automations app.
- Plan to run Neon: List Projects as your first step: the project ID it returns feeds every other Neon node.
Create a Neon API key
Mattering authenticates to Neon with an API key sent as a Bearer header on every request. Neon offers three variants: a personal key, which any user can create and which reaches the projects that user can access, an organization key, and a project-scoped organization key, both created by organization admins. All three are sent identically, so the integration accepts any of them; the difference is reach. A project-scoped key works only inside its project, which is a feature, not a limitation: it is the least-privilege credential for a single-project workflow.
Connect Neon to Mattering
Verify it works
After connecting, open any automation canvas and check the palette: a Neon section should list the query and action nodes. Drop Neon: Get Current User onto the canvas and run a test step. It is the integration's universal probe: it takes no parameters, works with every key variant, and returns the authenticated account's id, email, and plan without ever echoing the key. If this node succeeds, the credential is healthy; anything failing after it is a scoping or parameters question, not an authentication one.
Next, run Neon: List Projects and copy a project ID, because every other Neon node needs one, then run Neon: List Branches for that project: the branch ID it returns feeds the database, role, and compute endpoint nodes, and the response marks which branch is the default. Everything in this verify path is read-only: it cannot reach the five destructive nodes or change a single setting, so it is safe to re-run whenever you rotate the key.
Node reference
39 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 20
Neon: Get Branch
neon_get_branch
Fetch one branch: parent, default flag, protected flag, state, and usage counters.
Neon: Get Branch Consumption
neon_get_branch_consumption
Per-BRANCH consumption history for 1 to 100 named projects at hourly, daily, or monthly granularity - the finest-grained cost attribution Neon offers (which branch is burning the compute). Metrics come back as name-value pairs; extra_branches_month and snapshot_storage_bytes_month are NOT supported here (use Neon: Get Project Consumption). Per the API spec this endpoint serves paid usage-based Launch, Scale, Agent, and Enterprise plan accounts; org_id, metrics, and project_ids are required. Rows nest as data.branches[].periods[].consumption[].
Neon: Get Compute Endpoint
neon_get_endpoint
Fetch one compute endpoint: host, branch, type, state, autoscaling limits, and scale-to-zero timeout.
Neon: Get Connection URI
neon_get_connection_uri
Build a ready-to-use Postgres connection string for a database and role. Returns a LIVE credential - the URI embeds the role's password - and the value is stored in automation execution records, so treat downstream use accordingly. Defaults to the project's default branch and its read-write compute; set pooled to true for the -pooler (PgBouncer) host.
Neon: Get Current User
neon_get_current_user
Fetch the authenticated Neon account: id, email, login, plan, and project/branch limits. Works with any API key variant and no parameters - the credential health check to run first in any Neon automation.
Neon: Get Database
neon_get_database
Fetch one database on a branch: name, owning role, and timestamps.
Neon: Get Operation
neon_get_operation
Poll one operation until its status is finished (or failed / error). Statuses: scheduling, running, finished, failed, error, cancelling, cancelled, skipped. Every Neon write node returns the operation IDs to poll here in data.operations[].id.
Neon: Get Project
neon_get_project
Fetch one project: region, Postgres version, history retention, and current-period usage totals (compute time, active time, written data, storage).
Neon: Get Project Consumption
neon_get_project_consumption
Per-project consumption history in the current metric set, at hourly, daily, or monthly granularity. Each timeframe returns the requested metrics as name-value pairs (compute_unit_seconds, root_branch_bytes_month, child_branch_bytes_month, instant_restore_bytes_month, public/private_network_transfer_bytes, extra_branches_month, snapshot_storage_bytes_month). Per the API spec this endpoint serves Launch, Scale, Agent, Business, and Enterprise plan accounts; org_id and metrics are required. Does not wake any compute. Rows nest as data.projects[].periods[].consumption[].
Neon: Get Project Consumption (Legacy Metrics)
neon_get_consumption_legacy
Per-project consumption history in the LEGACY metric set: rows of active_time_seconds / compute_time_seconds / written_data_bytes (per-timeframe usage) and synthetic_storage_size_bytes (a storage SIZE snapshot - never sum it across timeframes) at hourly, daily, or monthly granularity. Per the API spec this endpoint serves Scale, Business, and Enterprise plan projects; newer plans use the v2 node. Does not wake any compute. Rows nest as data.projects[].periods[].consumption[].
Neon: Get Role
neon_get_role
Fetch one role on a branch: name, protected flag, and timestamps. The password is not included.
Neon: List API Keys
neon_list_api_keys
List the account's API keys: name, creation date, creator, and last-used time and address. Key TOKENS are never included - Neon only shows a token once at creation. Read-only audit surface; key creation and revocation stay in the Neon Console. Note: the response is a top-level ARRAY (data[0].id), not an object.
Neon: List Branches
neon_list_branches
List a project's branches with their IDs, parents, default flag, and state. The branch ID from here feeds the database, role, and compute nodes. NOTE: this lister's cursor lives at data.pagination.next (not .cursor like the other Neon listers).
Neon: List Compute Endpoints
neon_list_endpoints
List a project's compute endpoints with their IDs, hosts, branch bindings, types (read_write or read_only), and current state (active, idle...). The endpoint ID from here feeds the start, suspend, restart, update, and delete nodes.
Neon: List Databases
neon_list_databases
List the databases on a branch with their names and owning roles. Databases are branch-level in Neon: each branch carries its own copy.
Neon: List My Organizations
neon_list_my_organizations
List the organizations the authenticated account belongs to, with their org IDs and plans. The org_id from here scopes project listing and the consumption-metrics nodes.
Neon: List Operations
neon_list_operations
List a project's recent operations - the asynchronous work Neon schedules for writes (create_branch, start_compute, suspend_compute...) - newest first, with status and duration. Cursor paginated via data.pagination.cursor. The audit and monitoring view of everything the other action nodes kicked off.
Neon: List Projects
neon_list_projects
List the projects the API key can access, with their project IDs, regions, and Postgres versions. The project ID from here feeds every other Neon node. Cursor paginated: pass data.pagination.cursor back to get the next batch.
Neon: List Regions
neon_list_regions
List the regions Neon supports, with the region_id values Create Project accepts. Not all regions are available to all organizations - pass org_id for an accurate list.
Neon: List Roles
neon_list_roles
List the Postgres roles on a branch. Passwords are not included. Roles are branch-level in Neon: each branch carries its own copy.
Action nodes 19
Neon: Create Branch
neon_create_branch
Create a branch: a copy-on-write fork of the parent branch's data (or a point in its history via parent_lsn or parent_timestamp). Without an endpoints array the branch has NO compute and cannot accept connections - add one here or with Neon: Create Compute Endpoint. Branch creation is asynchronous; poll the returned operations. Reversible with Neon: Delete Branch.
Neon: Create Compute Endpoint
neon_create_endpoint
Create a compute endpoint on a branch: read_write (one per branch - fails if the branch already has one) or read_only (a read replica; multiple allowed). A branch created without compute needs this before anything can connect. Running compute accrues the project's compute usage. Reversible with Neon: Delete Compute Endpoint.
Neon: Create Database
neon_create_database
Create a database on a branch, owned by an existing role. Asynchronous - poll the returned operations. Reversible with Neon: Delete Database.
Neon: Create Project
neon_create_project
Create a Neon project: a new Postgres instance with a default branch, database, role, and read-write compute. Every field is optional - an empty config creates a project with generated names in the default region. The response includes connection URIs with LIVE credentials. Counts against the account or organization's project limit. Reversible with Neon: Delete Project.
Neon: Create Role
neon_create_role
Create a Postgres role on a branch. The response includes the generated PASSWORD (a live credential stored in automation execution records) - it is also recoverable later via a password reset. Reversible with Neon: Delete Role.
Neon: Delete Branch
neon_delete_branch
DESTRUCTIVE: delete a branch with its databases, roles, and compute endpoints; connections to it stop working. By default the delete is soft - the API spec documents a 7-day recovery window - but hard_delete=true removes it immediately and permanently. The default branch, a protected branch, and a branch with children cannot be deleted.
Neon: Delete Compute Endpoint
neon_delete_endpoint
DESTRUCTIVE: delete a compute endpoint. Neon documents that a compute deleted and added back later gets different connection details, so every connection string naming this one breaks permanently. Branch data is untouched.
Neon: Delete Database
neon_delete_database
DESTRUCTIVE: drop a database from a branch. Every table and row in it on THIS branch is gone (other branches keep their own copies). Recoverable only through the project's point-in-time restore window, if any.
Neon: Delete Project
neon_delete_project
DESTRUCTIVE: delete a project and EVERYTHING in it - all branches, databases, roles, and compute endpoints. Every connection string to the project stops working immediately. Neon keeps recently deleted projects recoverable for a limited window via the Console, but treat this as permanent: export anything you need first.
Neon: Delete Role
neon_delete_role
DESTRUCTIVE: delete a role from a branch. Anything authenticating as it stops working immediately, and the role's grants are gone. A role that owns a database cannot be deleted - reassign ownership first with Neon: Update Database.
Neon: Reset Role Password
neon_reset_role_password
Generate a new password for a role. The OLD password stops working immediately and cannot be recovered, so every client using it must be updated with the new one - which is returned in the response (a live credential stored in automation execution records). The credential-rotation node.
Neon: Restart Compute Endpoint
neon_restart_endpoint
Restart a compute endpoint (suspend then start). Open connections drop and there is a brief outage while it comes back - the standard fix for a wedged compute or to apply pending configuration.
Neon: Set Default Branch
neon_set_default_branch
Make a branch the project's default (primary) branch - the one connection URIs and branch creation fall back to when no branch is named. The previous default stays intact, so this is reversible by setting it back.
Neon: Start Compute Endpoint
neon_start_endpoint
Start a suspended compute endpoint so it can accept connections (the warm-up move before a batch job, instead of eating a cold start). Running compute accrues the project's compute usage. Asynchronous - poll the returned operation. Reversible with Neon: Suspend Compute Endpoint.
Neon: Suspend Compute Endpoint
neon_suspend_endpoint
Suspend a compute endpoint immediately (scale to zero now rather than waiting for the idle timeout). Open connections drop; the next connection wakes it with a cold start. Reversible with Neon: Start Compute Endpoint.
Neon: Update Branch
neon_update_branch
Update a branch: rename it, toggle the protected flag, or set an expiry time for automatic deletion. Only fields you fill are sent.
Neon: Update Compute Endpoint
neon_update_endpoint
Update a compute endpoint: change autoscaling limits, the scale-to-zero timeout, the display name, or disable connections (disabled=true schedules a suspend). Only fields you fill are sent; the change may restart the compute via the returned operations.
Neon: Update Database
neon_update_database
Rename a database or transfer it to a different owning role. Renaming breaks connection strings that name the old database. Only fields you fill are sent.
Neon: Update Project
neon_update_project
Update project properties: rename it, change the point-in-time restore window, or change the default compute autoscaling and scale-to-zero settings. Only fields you fill are sent. Reversible by writing the previous values back (read them first with Neon: Get Project).
Using the integration
On the automation canvas
Neon nodes chain with every other node: a pull request webhook can run Neon: Create Branch and then open a review task in Mattering Productivity, a scheduled sweep can read Neon: Get Project Consumption and write the numbers into a Mattering database, and Neon: List Compute Endpoints can feed a report on which computes are running. The IDs flow in one direction: the project ID from Neon: List Projects feeds everything, the branch ID from Neon: List Branches feeds the database, role, and compute nodes, and the endpoint ID from Neon: List Compute Endpoints feeds the start, suspend, restart, update, and delete nodes.
From AI assistants over MCP
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter can drive the same surface. Neon also hosts its own official MCP server at mcp.neon.tech, which is a good fit when an assistant only needs Neon; this integration is the fit when Neon is one step in a workflow that also touches other connectors and the Mattering platform. An agent here can list projects, branch a database, poll the operation, and fetch a connection string. The read nodes are the safest surface to hand an agent; keep the five destructive nodes behind conditions or approval steps.
Branching, and the compute a branch needs
Neon: Create Branch forks the parent branch's data copy-on-write, or a point in its history via a log sequence number or timestamp. The one thing that surprises everyone: a branch created without an endpoints array has no compute and cannot accept connections, so either include one in the create or follow up with Neon: Create Compute Endpoint. A branch carries its own copy of the parent's databases and roles, which is why the database and role nodes all take a branch ID. Neon: Update Branch renames, toggles the protected flag, or sets an expiry time for automatic deletion, and Neon: Set Default Branch moves the project's default, reversibly, since the previous default stays intact.
The asynchronous operations model
Most Neon writes schedule work rather than finishing it: the response includes an operations array naming what Neon queued, and the resource is not ready until those operations finish. Neon: Get Operation polls one operation until its status reaches finished, failed, or error, and that polling step belongs between any Neon write and the step that depends on its result, most visibly between creating a branch and fetching its connection string. Neon: List Operations is the audit view, a project's recent operations newest first with status and duration, so a monitoring workflow can catch failures instead of assuming silence means success.
The five destructive nodes, gated
Neon: Delete Project is the heaviest: it removes every branch, database, role, and compute endpoint, and every connection string to the project stops working immediately, so export anything you need first. Neon: Delete Branch is soft by default, with a 7-day recovery grace period documented in Neon's API and hard delete as an explicit opt-in, though Neon marks branch recovery as a preview feature not available to all users, so treat the grace period as a safety net rather than a guarantee; Neon also refuses to delete the default branch, a protected branch, or a branch with children. Neon: Delete Compute Endpoint is final in a specific way: Neon documents that a compute deleted and added back later gets different connection details, so every connection string naming the old endpoint breaks permanently even though the branch data survives. Neon: Delete Database drops that branch's copy while other branches keep theirs, and Neon: Delete Role cuts off anything authenticating as the role. The pattern for all five is the same: read the thing first, and put the delete behind a condition, an approval task, or a manual run rather than a bare trigger.
Live credentials, and what stays off the canvas
Four responses carry live credentials, and their nodes say so: Neon: Get Connection URI returns a Postgres URI with the role's password embedded, Neon: Create Project returns connection URIs for the new project, and Neon: Create Role and Neon: Reset Role Password return the role's password. Those values land in automation execution records, so pass them only where they are needed. The deliberate absences point the same direction: API key creation and revocation stay in the Neon Console, Neon: List API Keys is a read-only audit that never includes token material because Neon only shows a token once, and the reveal-password endpoint is not shipped, with Neon: Reset Role Password as the supported rotation move. Executing SQL is also out of scope: this integration manages the platform, and the connection string it hands out is how something else connects to run queries.
Troubleshooting
Test Connection fails with an authentication error
Test Connection passes but project nodes return not-found errors
The consumption nodes fail while everything else works
A branch was created but nothing can connect to it
A write node succeeded but the resource is not ready
Neon: Delete Branch refuses to delete a branch
Connection strings broke after a compute endpoint was deleted and recreated
Neon: Create Compute Endpoint fails on a branch that already has compute
Related
The Neon MCP
What connecting Neon unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
Neon is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.