n8n MCP server and client setup

The first decision is which direction each integration runs. An n8n workflow that starts with the MCP Server Trigger becomes a tool that an external MCP client can call, such as an AI assistant or another agent application. An agent node runs the other way: it connects out to an external MCP server and uses the tools that server offers. Both patterns use the same protocol, but they create different trust boundaries. In the first, your instance accepts requests from a client you may not control. In the second, your instance sends requests to a server you may not operate. Confirm the exact trigger and agent node names, along with the option fields for authentication and tool selection, in the current n8n documentation before you finalize the design, because these labels change between releases.

Write tool names and descriptions for the model that will call them. n8n takes tool names, descriptions and input parameters from the workflow design. The model reads these to decide whether to use a tool and what to send to it. Write the name as a short verb phrase that states the outcome, such as an order status lookup. Write the description as the instruction the model needs: when to call the tool, what it returns and what it does not do. Name each input parameter for its meaning, state its expected format, and mark whether it is required. Vague descriptions cause wrong calls, and a model that cannot tell two similar tools apart will often pick the wrong one. Review names and descriptions with the people who will use the client, not only with the workflow builders.

Exposed workflows run inside your own n8n instance, using the credentials and network access that instance already has. The external client never receives those credentials, but it does receive whatever the workflow returns, so the output is part of your data exposure. Keep a register of every exposed workflow with its owner, purpose, the systems it touches and whether it writes data. Return only the fields the caller needs, and avoid passing raw records containing personal or financial data to the model unless your policy allows it. Decide whether write actions should require a separate approval step before the tool runs. Your hosting design still determines where executions happen, so confirm that the exposed endpoint sits behind the controls your security team has already approved for webhooks.

When an agent node connects to an external MCP server, the tool names, descriptions and schemas come from that server's provider. You cannot rewrite them in your workflow, so the agent's behavior depends on how the provider described them. Before connecting, list the tools the server advertises, check which ones modify data, and identify the credential each one would use. If the agent node offers a way to limit which tools are available, confirm the option name in the current documentation and allow only what the use case needs. Pin the server version where the provider supports it, and recheck the tool list after every upgrade, because a new tool or a changed description can alter what the agent does without any change to your workflow.

Test the mapping before any user depends on it. Connect the client to a test instance, confirm that the tool list it displays matches your design, and run prompts that sit close to the wrong tool to see whether the model selects the right one. Check each execution in the n8n logs to confirm the inputs were parsed as intended. Plan for change as well: when a workflow's inputs change, the client may keep an outdated view of the tool, so retest after every edit. Confirm with n8n's pricing page how executions are counted on your plan, since each tool call that runs a workflow may count toward that total.

The single-replica routing rule matters because it limits where the MCP endpoint can run once n8n moves into queue mode. In queue mode, the main instance handles triggers and webhooks, then passes executions through Redis to a pool of workers. Those workers read and write workflow data in PostgreSQL. The MCP Server Trigger endpoint has to be placed on this topology deliberately, and the team should treat the routing rule as a hard architectural constraint rather than a setting to tune later. Before you size the cluster, read the current queue mode and MCP documentation to confirm the exact rule for your n8n version and whether n8n documents any workaround. Base the architecture on that confirmed text.

Designing around the rule starts with a diagram that shows which process hosts each MCP endpoint, how clients reach it, and what happens when that process restarts. Decide who owns the entry point: a single replica behind a stable address, a reverse proxy that routes MCP paths to one instance, or a dedicated instance reserved for agent traffic. Each choice changes health checks, deployment order and the impact of a failed upgrade. Ask the team to write down the expected client behavior during a restart and test it in a staging environment that mirrors the production queue topology. Confirm with n8n's documentation how the endpoint behaves when its replica is replaced, because the answer determines how much retry logic your agents and MCP clients need.

The encryption key is the second constraint the team must plan for. In queue mode, the main instance's encryption key must be shared with all worker and webhook processor nodes so they can read credentials stored in the database. Credentials used by MCP client connections and by the tools behind your MCP server are part of that set. If a worker starts with a different key, executions that depend on stored credentials fail, and the symptoms can look like network or authentication faults. Store the key in your secrets manager, inject it into every node from the same source, and add a pipeline check that confirms all nodes hold the same value without printing it. Plan key rotation as a coordinated cluster-wide change with a tested rollback path.

High availability needs a separate decision. Multi-main setup, which runs several main instances to remove a single point of failure, is restricted to Enterprise self-hosted deployments. It is not available in the Community edition or on n8n Cloud. If your requirement is that MCP access survives the loss of a main instance, the license tier becomes part of the architecture, and the cost and terms belong in the written plan before the build starts. Confirm current plan entitlements on n8n's pricing page and with n8n directly, since packaging can change. Also confirm that your intended use fits the Sustainable Use License, which limits use to internal business purposes or non-commercial use. Put the license review and the architecture decision into the same sign-off.

Test each exposed tool as an interface contract before any agent calls it. Start from an MCP client that is separate from the agent you plan to use, connect it to the endpoint created by the MCP Server Trigger, and list the tools. Confirm that every workflow you meant to expose appears, that the tool names and descriptions match your intent, and that each input schema lists the required fields, types and allowed values you defined in the workflow. Agents choose tools partly from these descriptions, so an unclear description is a defect even when the workflow runs correctly. Save the exact names and schemas in your test log so later changes are easy to spot.

For each tool, run valid inputs first, covering required fields alone and then with optional fields, and confirm the output has the shape the agent expects. Then run negative inputs: missing required fields, wrong types, empty strings, oversized text, values outside the expected range and fields that are not in the schema. The tool should return a clear error without partial side effects. Illustrative example: a tool that creates a ticket should reject an empty title before it reaches the ticketing system, not after. For any tool that writes to a business system, agree with the system owner which test records are acceptable and how they will be removed afterward.

Confirm that authentication failures are rejected. Send requests with no credentials, with an incorrect credential, and with a credential that has been rotated or removed, and confirm that each one fails without running the workflow. Then test the production topology rather than a single-process test instance. In queue mode, the main instance receives the trigger and webhook traffic and passes executions to workers, so send requests through the same hostname, proxy and load balancer that agents will use. Confirm that the routing rule for the MCP trigger is in place, and that workers can read the credentials they need, which depends on the encryption key being shared with them. Run the same tests from the network path your agents use.

Confirm that failed executions are visible to the operations team. Deliberately trigger a failing run, then check that it appears in the executions list with enough detail to diagnose the cause and that the owning team receives the alert you have configured. If operations needs failures forwarded to an external logging platform, confirm the plan supports log streaming, because n8n's pricing page lists it only on the Business and Enterprise plans. Record every test with the date, the n8n version, the tool name, the input used, the result and the evidence. Because n8n ships minor releases roughly weekly, repeat the full suite after each upgrade you adopt, and treat any changed schema or failed case as a blocker for agent access until it is resolved.