Package Information
Available Nodes
Documentation generating…
Documentation
Cached MCP Client Tool
Prototype community node for n8n 3.2.2. No production workflow is changed or installed by this project.
Architecture
- Cached MCP Client Tool is a single AI-tool node. In the editor, its Tools to Cache selector fetches
tools/list, including every page. Selecting a tool saves its name, description and completeinputSchemaas JSON inside this node's parameters. Credentials and tokens are not copied. supplyData()uses only the stored definitions; it neither reads credentials nor opens a connection. Each individual call opens a fresh MCP session, callstools/callwithouttools/list, and closes the session. An unavailable server or MCPisErrorfails only the invoked tool.- Agent routing is also implemented through
execute(), with n8n's toolkit routing keys and reserved-argument handling. The toolkit has the structural shape used by n8n 3.2.2'sStructuredToolkitand existing Tool Middleware. - Both nodes use the existing
mcpOAuth2Apicredential. Expiring tokens are refreshed through n8n's credential helper; HTTP 401 triggers one refresh and retry. The existing n8n domain allowlist, egress filter and proxy-aware fetch are used. - Tool names are prefixed with the sanitized node name, as in n8n's MCP Client Tool. Renaming the node changes exposed names.
Generate and refresh the cache
The n8n 3.2.2 node API does not expose a generic button parameter that can write another parameter. Instead, this node uses n8n's built-in multi-select and its Refresh List action. Choosing each tool saves its schema automatically in the same node; no second node or JSON copy/paste is needed.
- In an isolated test workflow add Cached MCP Client Tool, and configure its MCP endpoint and optional existing MCP OAuth2 credential.
- In Tools to Cache, select the tools to expose and save the workflow. The dropdown stores complete JSON for each selected tool.
- To update schemas, choose the field's Refresh List action. Select the new tool entry and deselect its
(previously cached)entry. Save the workflow. Do not leave both versions of the same tool selected.
The editor may also load the list when the node opens or its credentials change. This is editor-time behaviour only: trigger initialization and calls to other tools never refresh the cache. If the server is down, already saved tool definitions remain usable for initialization.
Descriptions and schema defaults are regular workflow parameters. Do not expose secrets there. Use HTTPS for authenticated remote MCP servers; plain HTTP exposes credentials and data in transit.
Schemas and results
Full original input schemas remain in the selected-tool JSON values. JSON Schema draft-07, 2019-09 and 2020-12 are validated with AJV, including local $ref. External references are not fetched; missing references and unsupported dialects fail with a configuration error. As in n8n's built-in MCP node, schemas are converted to Zod for middleware and the MCP Trigger. This conversion is not guaranteed to reproduce every JSON Schema keyword in the advertised schema; AJV separately validates the cached original before the call. Test complex schemas and the returned tool list in staging.
Results follow the built-in n8n MCP tool convention: compatibility toolResult, then structuredContent, then MCP content. MCP isError and connection failures are reported as tool errors. With n8n's MCP Server Trigger, a thrown tool error is formatted as an MCP error response. Input validation can also fail before a network call.
On n8n, the node attempts to use the JSON-Schema-to-Zod converter from the running n8n LangChain package. This matters because MCP Trigger checks Zod types using instanceof; isolated dependency copies are not interchangeable. If n8n is launched in a nonstandard layout in which that package cannot be resolved from the main process, the local converter is used instead; verify this in a staging instance before use.
Local development
Requires Node.js 24 or later. From this directory:
npm ci --ignore-scripts
npm test
npm pack
The tests exercise a local HTTP MCP server, editor-time selection, OAuth refresh via a mock n8n helper, pagination, cache-only initialization, per-call isolation, isError, timeout, JSON Schema and the workspace's existing Tool Middleware. They do not install or test the package in a real n8n process.
Install the packed community package only in an isolated n8n 3.2.2 test instance, then verify the selector, MCP Server Trigger tools/list and tools/call, OAuth refresh, and middleware. Deployment or modification of production workflows requires separate approval.