n8n-nodes-algenta

Docs: docs.algenta.ai · All integrations

An n8n community node for Algenta: a governed-execution-aware
node exposing your own self-hosted Algenta engine's MCP tool surface as typed n8n operations —
Get Contract, Query Data, Simulate, Recommend, Plan Decision, Log Decision, and
Execute Decision — with a real ExecutionReceipt / named-safety-gate contract on the last one.

n8n already ships a generic, built-in MCP Client node that can call any MCP server, including
Algenta's. This package is not a replacement for that — it exists for the value a generic node
can't give you: typed per-operation parameters instead of a hand-built JSON blob, a proper
ExecutionReceipt in a successful Execute Decision's output, a NodeApiError naming the real
policy gate (idempotency / confidence / risk_floor) when one blocks it, and a Tool Profile
selector that refuses Execute Decision outright under observe/govern — enforced before any
network call, including when this node is wrapped as a tool inside an n8n AI Agent.

Prerequisites

Before doing anything below, have these ready:

• Node.js 18.10+ — and pnpm 9+ as well, only if you build or develop this package from
  source instead of installing the published npm package.
• A running self-hosted Algenta engine, reachable over HTTP — for example http://localhost:8000.
  This node never talks to an Algenta-hosted cloud endpoint; there isn't one to point it at. If you
  don't have an engine running yet, see Self-host the engine.
• An API key, only if your engine enforces authentication. Engines running with auth disabled
  (e.g. local development) don't need one.
• n8n itself, if you want to see the node running inside the n8n editor rather than just
  building and testing it. The Quickstart below covers getting n8n running with
  zero prior n8n experience.

Install

Inside your own n8n instance:

npm install n8n-nodes-algenta

or install n8n-nodes-algenta from n8n's Community Nodes settings page, then restart n8n. To
build from source instead — for development, or to try the node in a throwaway local n8n before
connecting it to an engine — see the Quickstart below.

Quickstart

Try it locally (no Algenta engine required)

This gets the real node loaded into a real, local n8n editor so you can see its operations, typed
fields, and Tool Profile selector — no self-hosted engine needed yet, since nothing here calls one:

git clone https://github.com/thyn-ai/algenta-integrations.git
cd algenta-integrations/typescript/n8n-nodes-algenta
pnpm install
pnpm --filter n8n-nodes-algenta dev

pnpm dev (via @n8n/node-cli) symlinks this
package into a throwaway local n8n user folder and launches a real n8n instance with it already
installed — no npm publish and no manual community-node install step. Once it logs
Editor is now accessible, open http://localhost:5678, create a new workflow, and add an
Algenta node. Adding an Algenta API credential and pressing Test at this point will
fail with a plain connection error (nothing is listening on http://localhost:8000) — that is the
expected, correct result with no engine running yet, not a bug.

Run the full example (needs a running engine)

Once you have a self-hosted Algenta engine reachable (see Prerequisites), import
demo/n8n/log-and-execute-decision.json —
a real workflow that logs a decision and executes it, branching on whether the engine's policy
allowed or blocked the execution. See demo/n8n/README.md for
the exact import steps and what each node in it does.

Self-hosted-first

This node talks to your own self-hosted Algenta engine over its MCP endpoint ({baseUrl}/mcp)
— never a hosted-by-Algenta cloud service. Configure Base URL (default
http://localhost:8000, no /mcp suffix — the node appends it) and, if your engine requires one,
an API Key (sent as a bearer token) on the Algenta API credential.

Tool profiles

Matches contracts/integration-tool-contract.json
exactly — see test/contract-parity.test.ts.

Arguments

Get Contract and Execute Decision (Decision ID and Webhook URL) have real typed fields. The other
five operations take a JSON Arguments object, because their exact shape is discovered from the
connected engine's own MCP contract at call time and can vary by engine version — hardcoding typed
fields for them would mean guessing a schema no other package in this repository assumes either
(see algenta-tools/src/toolset.ts's identical reasoning for the sibling Vercel AI SDK package).

Why @modelcontextprotocol/sdk directly

n8n's own bundled MCP nodes use the official TypeScript SDK under the hood, and Algenta's MCP
server speaks the same protocol (Streamable HTTP, bearer auth) those nodes already talk to — so
this package uses the same SDK directly rather than depending on algenta-tools (which is built
around the Vercel AI SDK's ToolSet abstraction, a different execution model than n8n's own node
execute() lifecycle).

n8n Cloud eligibility

This node is not eligible for n8n's Cloud verification program — that program requires zero
runtime dependencies (community nodes share one n8n instance's node_modules, so n8n Cloud bans
anything that could conflict), and this node genuinely needs @modelcontextprotocol/sdk to speak
MCP correctly rather than hand-rolling the protocol's session/handshake/SSE framing. It is a fully
real, tested community node for self-hosted n8n — this program's actual target audience —
installed the normal way (npm install n8n-nodes-algenta inside your n8n instance, or via the
Community Nodes settings page). n8n-node lint accordingly runs against
configWithoutCloudSupport, not the default strict/cloud config; see eslint.config.mjs.

Two lint findings are deliberately left as documented exceptions rather than "fixed" into
something worse:

• The "dependencies" field lint (@n8n/community-nodes/no-runtime-dependencies) flags
  @modelcontextprotocol/sdk — the same tradeoff as above, not an oversight.
• import-x/no-unresolved on the SDK's client/*.js and server/*.js subpath imports is the
  bundled eslint config's resolver not following the SDK's exports map in this setup; tsc
  resolves them correctly (see pnpm build) and the test suite exercises them over a real socket.

Development

pnpm install
pnpm build
pnpm test
pnpm lint

Tests run a real @modelcontextprotocol/sdk McpServer over a real local HTTP socket
(test/test-support/stub-server.ts) and exercise this package's actual client/node code against
it — not a mock of the SDK's internals.

License

This package's package.json declares "license": "Apache-2.0", matching the rest of this
repository (the root LICENSE, NOTICE, and the
workspace root package.json).

n8n's own community-node verification lint
(n8n-nodes-base/community-package-json-license-not-default) hard-requires this field to read
exactly MIT on any package carrying the n8n-community-node-package keyword — this package
deliberately does not comply, and that rule is turned off in eslint.config.mjs with a comment
explaining why. This is a deliberate, informed choice: org-wide license consistency across every
package in this repository was judged more important than eligibility for n8n's official
community-node registry listing. The practical consequence is that this node likely cannot be
submitted to or discovered through that registry, but it remains a fully real, tested, installable
community node for self-hosted n8n via direct install (npm install, or building from source —
see "Development" above).