cervio

n8n community node for Cervio — entity records, documents, N:M links, workflows, and notifications via REST /api/v1

Documentation

@cervio/n8n-nodes-cervio

npm version
CI
License: MIT
made by cervio.app

Cervio n8n node — create a record then list via view

Official n8n community node for Cervio.

Connect n8n workflows to a Cervio tenant over the public REST API (/api/v1): entity records, documents, N:M links, upsert/resolve, workflows, and notifications. Field lists for create/update come from the form write-schema (resource mapper), not a free-form JSON body. The node is marked usableAsTool: true (optional REST tool for AI Agent). For the full Cervio MCP tool surface, use n8n’s built-in MCP Client Tool — see AI Agent + Cervio MCP.

Website cervio.app
npm @cervio/n8n-nodes-cervio
Source github.com/cervio-app/n8n-nodes-cervio
Issues GitHub Issues
Changelog CHANGELOG.md
Node type @cervio/n8n-nodes-cervio.cervio

Maintained by Cervio. Support: Issues or dev@cervio.app.

Migration: the unscoped package n8n-nodes-cervio is deprecated. Install @cervio/n8n-nodes-cervio and re-select the Cervio credential / node if n8n cached the old type name.

Prerequisites

  • Node.js ≥ 20
  • An n8n instance (self-hosted, desktop, or Cloud with community packages enabled)
  • A Cervio Personal Access Token (cpat_…) from Admin → API
  • External API access enabled for the organization

Installation

n8n UI (recommended)

  1. Open Settings → Community nodes
  2. Install @cervio/n8n-nodes-cervio
  3. Restart n8n if prompted

npm + custom folder

npm install -g @cervio/n8n-nodes-cervio

mkdir -p ~/.n8n/custom
cd ~/.n8n/custom
npm link @cervio/n8n-nodes-cervio

Restart n8n, then add the Cervio node from the palette.

From source

git clone https://github.com/cervio-app/n8n-nodes-cervio.git
cd n8n-nodes-cervio
npm install && npm run build
npm link

mkdir -p ~/.n8n/custom && cd ~/.n8n/custom
npm link @cervio/n8n-nodes-cervio

Docker Compose (local n8n)

Uses compose.yaml with a pinned n8nio/n8n image and this package bind-mounted via N8N_CUSTOM_EXTENSIONS:

npm run build
docker compose -f compose.yaml up
# → http://localhost:5678

Optional image bake: Dockerfile (same pin, N8N_CUSTOM_EXTENSIONS=/opt/n8n-nodes-cervio only).

Live API smoke scripts (npm run smoke*) are separate — see CONTRIBUTING.md.

Credentials

Create a Cervio API credential in n8n:

Field Example Notes
Base URL https://acme.cervio.app Tenant host only — required, no default. Must be http/https. Link-local / cloud-metadata hosts (169.254.0.0/16, metadata.google.internal, …) are rejected.
Personal Access Token cpat_… From Cervio Admin → API

All operations use this credential.

Operations

Pick a Resource, then an Operation (node typeVersion 2 only):

Resource Operation Description
Record Create / Update / Get / Delete CRUD through an assigned form mask
Create or Update (upsert) Natural-key create-or-update (match_field)
Validate draft Dry-run formulas / required fields
List view Read via an assigned list view (cursor pages)
List Admin entity list with filter[field]=eq.value
Relation Search Browse/search relation candidates (q, limit ≤ 100)
Resolve Key Match scalar keys → record UUIDs
Link / Unlink N:M through-field links
Document List / Upload / Open Metadata, multipart upload, signed URL
Generate from Template Render a mapped document template (admin)
Workflow Start / Get Run Status Manual start + admin run status
Notification Send to Me Inbox (+ push if enabled) for the PAT owner
Notify Users Up to 50 org members (admin)

Notes

  • Create / Update / Upsert / Validate: pick Entity → Form, then the resource mapper.
  • N:M through fields are not on the mapper — use Link / Unlink.
  • Relation dropdowns are capped (~50); use Search relation for larger sets.
  • List view defaults: options = slugs, relations = UUIDs (ready for Update).
  • Start workflow → Additional Data: Key/Value rows or a JSON object (same data body Cervio accepts on POST /api/v1/workflows/:id/runs, max 64 KiB → $trigger.data).

Permissions

There is no n8n-specific ACL in Cervio. The node is a REST client; Cervio applies two layers. Both must allow the call.

n8n  ──Bearer cpat_…──►  1) PAT scopes (Admin → API)
                              │  fail → 401 / scope error
                              ▼
                         2) User who owns the PAT (same ACL as UI)
                              │  fail → 403 / 404 / empty / validation

Token scopes

Scope Used for
records:read Get, List view/records, Search/Resolve, List/Open documents
records:write Create, Update, Delete, Upsert, Validate, Upload, Link/Unlink, Start workflow
admin:read Form / view / workflow dropdowns, Get workflow run
admin:write Generate document from template; Notify Users
me:write Send to Me (self notification)

*:write implies the matching *:read. Scopes alone do not grant row access or can_create. Org notifications must be enabled or Cervio returns 403 notifications_disabled.

User behind the PAT

The PAT impersonates its owner (entity permissions, record policies, field denials, form/view assignments, document capabilities, manual-workflow trigger ACL) — same as the UI.

Setup PAT owner Scopes
Full guided UX system_admin admin:read, admin:write, records:read, records:write, me:write
Narrow sync Service user with entity ACL + assigned views/forms records:read / records:write only

AI Agent + Cervio MCP

For an AI Agent that should call Cervio’s full MCP tool set (records, forms, workflows, admin tools filtered by PAT scopes), use n8n’s built-in MCP Client Tool — not a custom Cervio MCP node in this package.

  1. AI Agent → Tool → MCP Client Tool
  2. Endpoint: https://YOUR_TENANT.cervio.app/api/mcp (same host as the Cervio API Base URL)
  3. Server Transport: HTTP Streamable (do not use deprecated SSE)
  4. Authentication: Bearer Auth — create an n8n Bearer credential with the raw PAT cpat_… only (no Bearer prefix)
  5. Tenant: External API enabled for the org; PAT scopes non-empty and adequate for the tools you need (tools outside scope disappear from tools/list)
  6. Tools to Include: All or a subset

The Bearer credential is a separate n8n credential entry from Cervio API (community node limit): same PAT value, two credential rows.

Optional / narrower: this package’s node is usableAsTool: true, so you can also attach Cervio Tool for a single fixed Resource + Operation (REST). That does not expose the full MCP surface.

We intentionally do not ship a wrapper MCP client here: n8n owns transport and protocol updates; a thin Cervio-branded MCP Tool (reuse cervioApi credential, auto URL) may come later if onboarding friction justifies it.

Compatibility

n8n Community nodes API v1 (n8nNodesApiVersion: 1); local Compose pin n8nio/n8n:2.47.2
Node.js ≥ 20 (build / smoke); CI uses Node 22
Cervio Tenant with /api/v1 and External API enabled
Node typeVersion 2 only (Resource + Operation)

Development

npm install
npm run build
npm test
npm run verify
npm run lint

Conventions, SemVer tags (vX.Y.Z), and publish steps: CONTRIBUTING.md.

Live smoke (optional):

export CERVIO_BASE_URL=https://YOUR_TENANT.cervio.app
export CERVIO_PAT=cpat_…
npm run smoke
npm run smoke:extended

Known limits

  • List records without a view is admin-only — prefer List view
  • Nested child create = two Creates (parent, then child with FK)
  • Generate document needs a mapped template UUID (no public template catalog yet)
  • List view “all pages”: max 10 × 500 rows

Code of Conduct

See CODE_OF_CONDUCT.md.

References

License

MIT

Discussion