n8n Documentation Guide: Build AI Workflows and Connect Claude, Codex, and More

Introduction: Why n8n Documentation Matters for Modern Automation

The n8n docs at docs.n8n.io are more than a reference manual — they're the entry point to one of the most flexible workflow automation platforms available today. n8n is a fair-code licensed workflow automation tool that combines AI capabilities with business process automation, letting technical teams build everything from simple data syncs to multi-step AI agent pipelines.

If you're evaluating automation platforms or preparing to connect an AI model like Claude to your internal systems, understanding the documentation structure saves hours of trial and error. This guide walks through the complete documentation index, setup paths, core concepts, and — critically — how to connect Anthropic's Claude Desktop and Claude Code, plus OpenAI's Codex CLI, to an n8n MCP server over HTTP.

Whether you're a solo builder or part of a team delivering AI model training services and integrations, this breakdown gives you a practical map of the docs.

What Is n8n? A Fair-Code Automation Platform Explained

n8n (pronounced "n-eight-n," short for "nodemation") is a source-available workflow automation tool. Its fair-code license means the source is publicly available and you can self-host it, while commercial use of the hosted cloud version follows a sustainable business model. This matters for organizations that need data residency, auditability, or on-premise deployment.

Key Characteristics

• Visual, node-based editor: You build workflows by connecting nodes on a canvas rather than writing glue code from scratch.
• Code when you need it: The Code node lets you drop in JavaScript or Python for custom logic, so you're never blocked by missing integrations.
• AI-native features: Native nodes for AI agents, chat triggers, and vector stores make it a strong fit for LLM-powered automation.
• Self-host or cloud: Run it via Docker, Docker Compose, a cloud provider, or n8n's managed cloud.

Expert insight: The combination of a visual builder and escape hatches (Code node, HTTP Request node) is what separates n8n from purely no-code tools. In practice, teams often prototype visually, then refactor the heaviest logic into code nodes for maintainability.

Navigating the Complete Documentation Index

The documentation site provides a complete documentation index via llms.txt — a machine-readable file designed so that LLMs and AI assistants can ingest the docs efficiently. This is a deliberate, forward-looking choice: as more developers use AI coding assistants, having a structured index means an AI agent can answer "how do I do X in n8n?" accurately.

Markdown Availability

Every documentation page is also available as Markdown. This is genuinely useful for two reasons:

1. Version control and diffing: You can store doc snippets alongside your workflow JSON in Git.
2. AI ingestion: Markdown is the preferred format for retrieval-augmented generation (RAG) pipelines. If you're building internal tooling that references n8n docs, you can fetch the Markdown version directly.

Actionable tip: If you maintain an internal knowledge base, script a job that pulls the Markdown versions of the n8n docs you rely on most. Re-run it periodically so your team's reference stays current.

Getting Set Up on n8n

The documentation offers several setup routes, and choosing the right one depends on your environment and compliance needs.

Option 1: Try Free, Then Choose a Plan

The fastest path is to try n8n free and then select a plan. This is ideal for evaluation — you can build a proof-of-concept workflow before committing to infrastructure.

Option 2: One-Line Setup

n8n provides a one-line setup command for quick local installation. This is the quickest way to get a running instance for experimentation.

Option 3: Install Using Docker Compose

For teams, Docker Compose is often the sweet spot. You get reproducibility, easy upgrades, and the ability to add a database (PostgreSQL) and queue mode for scaling.

A typical Compose setup includes:

• The n8n container
• A PostgreSQL database for persistence
• Optional Redis for queue-based execution

Best practice: Pin your image version (for example, a specific tag rather than latest) so an unattended upgrade doesn't break production workflows.

Option 4: Use a Cloud Provider

If you prefer managed infrastructure, you can deploy via a cloud provider. This suits teams that want the control of self-hosting without managing servers directly.

Comparison at a Glance

Build Your First Workflow

The documentation's "Build your first workflow" section is the logical starting point. A workflow in n8n is a series of nodes connected by lines, triggered by an event.

A Practical Starter Example

Imagine you want to log new form submissions to a database and notify a Slack channel:

1. Trigger node: A Webhook node receives the form POST.
2. Transform node: A Set or Code node normalizes the fields.
3. Action node: A database node inserts the record.
4. Notification node: A Slack node posts a summary.

This four-node pattern — trigger, transform, store, notify — is the backbone of a huge share of real-world automations.

Getting Inspiration for What to Automate

The docs include example workflows to spark ideas. A few categories worth exploring:

• Creating an API endpoint: Use a Webhook trigger to expose a lightweight API backed by your workflow logic.
• AI agent chat: Build a conversational agent that can call tools and retrieve data.
• Scrape and summarize web pages with AI: Fetch a page, extract content, and pass it to an LLM for summarization.
• Joining different datasets: Merge records from two sources using matching keys — a common data-ops task.

Expert insight: Start with the "joining different datasets" example if you come from a data background. It teaches you n8n's item-based data model, which is the single most important mental model to internalize.

Understand Key Concepts

Before building complex workflows, the documentation recommends understanding a handful of core concepts. Skipping this step is the most common cause of frustration.

Expressions for Data Transformation

Expressions let you reference data dynamically using {{ }} syntax. For example, to reference a value from a previous node, you might write an expression that pulls a field from the incoming item. Expressions are how you avoid hardcoding values.

Flow Logic

Flow logic covers branching and control: IF nodes, Switch nodes, Merge nodes, and loops. This is where workflows go from linear scripts to genuine decision engines.

Understand Executions

Executions are individual runs of a workflow. The executions view shows input/output data per node, which is invaluable for debugging. You can inspect exactly what data entered and left each node.

Actionable tip: When a workflow fails, open the failed execution and click into the node that errored. The input data shown there usually reveals the problem immediately — often a null value or a type mismatch.

Connecting Claude Desktop to the n8n MCP Server

One of the most powerful recent additions to the n8n ecosystem is MCP (Model Context Protocol) support. MCP is an open standard that lets AI applications connect to external tools and data sources. By exposing an n8n MCP server, you let Claude Desktop trigger and interact with your workflows.

What This Enables

• Claude Desktop can call n8n workflows as tools.
• You can build an AI assistant that queries internal systems through n8n's existing integrations.
• Sensitive credentials stay in n8n; Claude only sees the tool interface.

The Connection Pattern

The documentation covers connecting Claude Desktop to the n8n MCP server. The general flow involves:

1. Enable the MCP server in your n8n instance.
2. Configure Claude Desktop to point at the n8n MCP endpoint.
3. Restart Claude Desktop and verify the tools appear.

Best practice: Treat your MCP endpoint like any other API — put it behind authentication and restrict which workflows are exposed. Never expose workflows that handle credentials or destructive operations without review.

Connecting Claude Code to the n8n MCP Server

For developers working in a terminal, Anthropic Claude Code can connect to n8n via MCP using a single command. The documentation provides a copy-ready command of the form:

claude mcp add --transport http n8n-mcp https://<your-instance>/mcp-server/http

Replace <your-instance> with your actual n8n host. The --transport http flag tells Claude Code to communicate over HTTP with the MCP server.

Why This Matters

This turns your terminal-based coding assistant into an orchestrator that can trigger automation. Practical scenarios include:

• Asking Claude Code to run a deployment workflow.
• Having it fetch data from a workflow before generating code.
• Automating repetitive ops tasks directly from your editor session.

Expert insight: Because the command is a single line, it's easy to script into developer onboarding. Store the command (with a placeholder host) in your team's setup docs so new engineers connect in seconds.

Connecting OpenAI Codex CLI to the n8n MCP Server

The docs also cover OpenAI Codex CLI, with a parallel command:

codex mcp add n8n-mcp --url https://<your-instance>/mcp-server/http

This registers the n8n MCP server with Codex CLI so the assistant can call your workflows as tools.

Claude vs. Codex: A Quick Comparison

Both approaches follow the same conceptual model: register a named MCP server, point it at the HTTP endpoint, and let the AI client discover available tools.

Actionable tip: Use the same server name (n8n-mcp) across clients. Consistent naming makes it easier to reason about which tools are available when you switch between assistants.

Practical Use Cases for AI-Driven Automation

Connecting AI clients to n8n unlocks workflows that would otherwise require custom middleware. Consider these examples:

1. Internal Knowledge Assistant

An employee asks Claude Desktop a question. Claude calls an n8n workflow that queries your documentation and returns an answer. n8n handles authentication and data retrieval; Claude handles the conversation.

2. Ticket Triage

A new support ticket arrives via webhook. An n8n workflow classifies it with an LLM, assigns a priority, and routes it. If the model is uncertain, it escalates to a human.

3. Data Enrichment Pipeline

A workflow scrapes a webpage, summarizes it with AI, and writes the result to a database. This is directly inspired by the docs' "scrape and summarize web pages with AI" example.

4. Developer Ops from the Terminal

A developer asks Claude Code to "run the staging seed workflow." Claude Code calls the n8n MCP tool, which triggers the workflow and returns the result.

Expert insight: The common thread is separation of concerns. AI models handle language and reasoning; n8n handles connectivity, credentials, and reliable execution. This division keeps systems auditable — a requirement for teams delivering AI model training services and enterprise integrations.

Best Practices for Working with n8n Documentation

1. Check the "last updated" date. The docs show when a page was last updated (the index page, for instance, indicated an update roughly 18 days prior at the time of writing). Automation platforms evolve quickly; stale tutorials can mislead.
2. Use the Markdown versions for AI pipelines. Feed them into your RAG system rather than scraping HTML.
3. Leverage llms.txt. Point your AI assistant at the complete documentation index for accurate, structured answers.
4. Read the concepts section before building. Expressions, flow logic, and executions are foundational.
5. Use the "Was this helpful?" feedback. It routes improvements back to the maintainers and helps other users.

Common Pitfalls and How to Avoid Them

• Ignoring the item-based data model. n8n processes arrays of items. Misunderstanding this leads to bugs when nodes return multiple items.
• Hardcoding credentials. Use n8n's credential store, not expressions containing secrets.
• Exposing MCP tools too broadly. Limit which workflows an AI client can call.
• Skipping error handling. Add error workflows or IF-based fallbacks so failures don't silently drop data.
• Not pinning versions in Docker. Unpinned images can change behavior unexpectedly.

Frequently Asked Questions

Is n8n free? n8n is fair-code licensed. You can self-host it, and there are paid cloud plans. Check the current licensing terms in the docs, as they can evolve.

Can I connect Claude and Codex at the same time? Yes. Both register against the same MCP HTTP endpoint under the name n8n-mcp, so multiple clients can coexist.

Do I need to write code? No — but the Code node and HTTP Request node give you an escape hatch when a prebuilt node doesn't exist.

Where do I start? Follow the "Build your first workflow" guide, then explore the example workflows for inspiration.

Conclusion: From Docs to Deployed Automation

The n8n documentation is structured to take you from zero to a working automation, then extend it with AI. The path is clear: get set up (free trial, one-line, Docker Compose, or cloud), build your first workflow, understand key concepts like expressions and executions, and then connect AI clients — Claude Desktop, Claude Code, and OpenAI Codex CLI — to the n8n MCP server over HTTP.

The bigger picture is that n8n sits at the intersection of business process automation and AI. As MCP adoption grows, the ability to expose workflows as callable tools will become a standard expectation, not a novelty. Teams that master this pattern now — especially those building AI model training services and internal AI tooling — will be positioned to ship faster and more safely.

Start with the docs, build one workflow, connect one AI client, and iterate. The documentation index and Markdown versions make it easy to keep your knowledge current as the platform evolves.