Menu

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.

Sign in at console.neon.tech and open your account menu. Select Account settings, then API keys.
For a key owned by an organization instead, switch to the organization and open Settings, then API keys, where admins can create an organization key or a project-scoped key.
Create a new key and give it a name that says what automation it serves, so a later audit of the key list reads cleanly.
Copy the key now. Neon displays the secret once, at creation, and never again; after you leave this screen your options are revoking it and creating a new one.
A project-scoped key returns not-found errors for anything outside its project. That is the scoping working as designed, so if you plan workflows across several projects, use a personal or organization key instead.

Connect Neon to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Neon from the list.
Click Create new credential, paste the API key, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection. Mattering calls Neon's current-user endpoint, which works with every key variant and takes no parameters: a successful result proves the credential, an error means the key is mistyped or revoked.
Click Connect. All 39 Neon nodes appear in your canvas palette.

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
The current-user probe accepts every valid key variant, so a failure here is about the key itself. Check for leading or trailing whitespace from the copy, and confirm the key still exists in the Neon Console: keys can be revoked, and a revoked key fails exactly like a wrong one. If the key was created moments ago and the value was not copied from the creation screen, it cannot be retrieved now; Neon shows the secret once, so revoke it and create a new one.
Test Connection passes but project nodes return not-found errors
The usual cause is a project-scoped organization key: it authenticates fine but returns not-found for every project except its own, by design. Run Neon: List Projects and look at what comes back; if the list is shorter than what the Neon Console shows, the key's scope is the answer. Use a personal or organization key for cross-project workflows, or keep the scoped key and accept that its workflows live inside one project.
The consumption nodes fail while everything else works
The consumption metrics family is plan-gated by Neon, per its API spec: 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. On a Free plan these nodes return errors while the other 36 work. Also check the required parameters: the two current nodes require an organization ID from Neon: List My Organizations and an explicit metrics list, the per-branch node requires named project IDs as well, and on the legacy node the organization ID and metrics list are optional filters.
A branch was created but nothing can connect to it
A branch created without an endpoints array has no compute, so there is nothing to accept the connection. Add a compute at creation time by including the endpoints array on Neon: Create Branch, or add one afterward with Neon: Create Compute Endpoint, then poll the returned operation with Neon: Get Operation before fetching a connection string. Neon: List Compute Endpoints for the project shows which branches have compute and which are storage-only.
A write node succeeded but the resource is not ready
That is Neon's asynchronous model rather than a fault: most writes schedule operations and return immediately, and the resource is usable only after those operations finish. Read the operations array on the write node's output and poll each ID with Neon: Get Operation until the status is finished; failed and error are terminal too, and mean the work did not complete. Workflows that skip the polling step and immediately act on a new branch or compute will race Neon and lose intermittently, which is the worst kind of bug to chase.
Neon: Delete Branch refuses to delete a branch
Neon blocks three deletes outright: the project's default branch, a branch with the protected flag set, and a branch that has child branches. For a default branch, promote another branch first with Neon: Set Default Branch. For a protected branch, clear the flag with Neon: Update Branch, which is deliberately a separate, gateable step. For a branch with children, delete or re-parent the children first; Neon: List Branches shows each branch's parent so a workflow can walk the tree bottom-up.
Connection strings broke after a compute endpoint was deleted and recreated
This is permanent, and worth designing around: Neon documents that a compute deleted and added back later gets different connection details, and the replacement carries a new generated ID and hostname, so every connection string naming the old endpoint is dead even though the branch and its data are intact. Fetch fresh connection strings with Neon: Get Connection URI after any endpoint replacement and deliver them to whatever connects. If the goal was only to stop a compute from running, Neon: Suspend Compute Endpoint does that reversibly without destroying the hostname.
Neon: Create Compute Endpoint fails on a branch that already has compute
A branch can carry only one read-write compute endpoint, so creating a second one fails; that is Neon's rule, not the integration's. Check what exists with Neon: List Compute Endpoints, which shows each endpoint's branch and type. If the branch needs more read capacity, create a read-only endpoint instead, since a branch can have several of those alongside its read-write compute. If the goal was to change the existing compute's size or timeout, use Neon: Update Compute Endpoint rather than creating a new one.

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.

Start Free Explore our Products