Agent Cost & UsageConnect n8n

Connect n8n

Use this integration for self-hosted n8n agent workflows.

The Mavvrik n8n SDK loads when n8n starts and captures workflow executions, workflow nodes, supported AI model calls, embeddings, vector retrievals, memory operations, and tool executions.

1. Register the n8n agent

In Mavvrik, go to Admin → Accounts → Agents, click + Agent, and select n8n.

Enter a connection name that identifies the n8n instance, then continue to Connect. Copy the environment variables shown in the Connect step.

2. Install the n8n SDK

Direct installation

npm install @mavvrikai/n8n-sdk

NODE_OPTIONS=--import @mavvrikai/n8n-sdk/register
MVK_ENABLED=true
MVK_CONNECTION_ID=...
MVK_API_KEY=...
MVK_TENANT_ID=...
MVK_ENDPOINT=...

NODE_OPTIONS preloads the Mavvrik SDK before n8n starts and enables automatic instrumentation. Restart n8n after setting the variables.

Docker installation

FROM docker.n8n.io/n8nio/n8n

ARG MVK_SDK_VERSION=latest
RUN npm install "@mavvrikai/n8n-sdk@${MVK_SDK_VERSION}"

ENV NODE_OPTIONS="--import @mavvrikai/n8n-sdk/register"
ENV MVK_ENABLED=true

services:
  n8n:
    build:
      context: .
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    env_file:
      - .env
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

Keep the n8n_data volume. n8n stores workflows, credentials, and its encryption key in /home/node/.n8n.

Add the Mavvrik values from the Connect step to .env, then rebuild and start:

docker compose up -d --build

What Mavvrik captures automatically

3. Verify the integration

Check the n8n logs after restart. A successful startup reports that n8n instrumentation is active.

Run a workflow containing a supported AI node. Open Home → Agentic → Cost and Home → Agentic → Sessions and confirm the workflow activity appears.

Add static business context

Use static context for values that remain the same for every execution on the n8n instance, such as environment, region, application, cost center, or business unit.

MVK_BUSINESS_CONTEXT='environment=production,region=us-east-1,tag_cost_center=platform'

If n8n runs in queue mode, set MVK_BUSINESS_CONTEXT on the main, worker, and webhook processes.

Add dynamic business context

Dynamic context applies to one workflow execution and can include customer, user, session, request, use case, or channel.

Place an Edit Fields (Set) node or Code node immediately after the workflow trigger.

The SDK captures business context once per workflow execution. Fields added later in the workflow are ignored for execution-level context.

Edit Fields (Set)

Add one field for each business attribute directly after the trigger. Use this when values can be mapped directly from the trigger input.

Code node

Use a Code node when the values must be derived.

return items.map(item => ({
  json: {
    ...item.json,

    customer_id: item.json.body.account,
    user_id: item.json.body.user,
    session_id: item.json.body.session,
    use_case: "customer_support",

    tag_channel: "support",
    tag_priority: "high"
  }
}));

Supported downstream activity inherits the captured context.

Recognized context fields

tenant_id
session_id
user_id
email_id
client_id
customer_id
request_id
region
use_case
agent_id
environment
run_id

Field names are matched case-insensitively. Values must be strings, numbers, or booleans. Objects and arrays are dropped rather than converted to first-class context values.

Add custom tags

Prefix additional reporting dimensions with tag_:

return items.map(item => ({
  json: {
    ...item.json,
    tag_department: "finance",
    tag_channel: "slack",
    tag_priority: "p1"
  }
}));

Custom tag rules:

• the first 10 custom tags are kept per workflow execution;

• tag names must use lowercase [a-z0-9._-] and be no longer than 64 characters;

• values are limited to 256 characters;

• a field that is neither a recognized context field nor tag_-prefixed is ignored.

These validation failures do not stop the n8n workflow.

Example: customer-support workflow

Place the business context node immediately after the webhook and set:

customer_id = acme
user_id = user-123
session_id = support-456
use_case = customer_support
tag_channel = web

The workflow execution, supported model calls, retrieval operations, and tools can then be inspected under the same customer and session in Mavvrik.

Configure trace propagation

The n8n SDK supports W3C traceparent and B3 trace propagation.

For publicly reachable webhooks, disable inbound propagation or strip untrusted trace headers at the edge if external callers must not influence internal trace context.

Troubleshoot n8n data

MVK_LOG_LEVEL=debug
MVK_PRINT_SUMMARY=human

Verify:

1. NODE_OPTIONS=--import @mavvrikai/n8n-sdk/register is present in the environment that starts n8n.

2. MVK_ENABLED=true.

3. Connection, tenant, API key, and endpoint values match the Mavvrik Connect step.

4. n8n was restarted after configuration changes.

5. The tested workflow contains a supported AI operation.

Verify the complete setup

If the workflow runs but Mavvrik data is incomplete, use Troubleshooting Agent Data.