AI Agent Integration

By registering NodeCrypto with an AI agent such as Claude Code or Claude Desktop, you can build cryptographic workflows in natural language. The agent reads the node catalog, authors a workflow draft, verifies it against test vectors, and saves it as an .ncw file. You then open that file in the web app to inspect and review it on the canvas.

• NodeCrypto runs as a lightweight local program (an MCP server) launched by the agent on your own computer. It makes no network connections and opens no network ports.
• Requirements: Node.js 20 or later, and an MCP-compatible AI agent.
• The agent is given five tools: guide (authoring guide), catalog (node lookup), validate (validation), run (execution and expected-value comparison), and expand (saving .ncw files).

Installation

Every MCP client uses the exact same server command: command npx, arguments -y @curealls/nodecrypto mcp. Only the configuration location differs by client.

Claude Code

Register the server with a single terminal command. Everything after -- is the command used to launch the server.

claude mcp add --transport stdio nodecrypto -- npx -y @curealls/nodecrypto mcp

• The default scope (local) registers it for the current project only. Add --scope user to make it available across all projects, or --scope project to save it in the project's .mcp.json file and share it with your team.
• Run claude mcp list and verify that nodecrypto appears as Connected. Inside Claude Code, you can also check with /mcp.

Claude Desktop

1. Open Settings from the Claude menu, go to the "Developer" tab, and click "Edit Config". This opens claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json, macOS: ~/Library/Application Support/Claude/claude_desktop_config.json).
2. Add the following configuration. If the file already has an mcpServers object, add only the nodecrypto entry inside it.

{
  "mcpServers": {
    "nodecrypto": {
      "command": "npx",
      "args": ["-y", "@curealls/nodecrypto", "mcp"]
    }
  }
}

3. Quit Claude Desktop completely and relaunch it. Click the "Add files, connectors, and more" button at the bottom-left of the chat input box and open connector settings to view the nodecrypto tools.

VS Code, Cursor, and Other Clients

Add the same command to your client's MCP configuration file. The file location and top-level JSON key vary by client.

VS Code example:

{
  "servers": {
    "nodecrypto": {
      "command": "npx",
      "args": ["-y", "@curealls/nodecrypto", "mcp"]
    }
  }
}

Cursor uses the same mcpServers structure as Claude Desktop. For any other MCP client, look for where it registers a "standard I/O (stdio) server: command npx, arguments -y @curealls/nodecrypto mcp".

Windows

• First verify in a terminal that node --version reports 20 or higher and that npx -y @curealls/nodecrypto --version runs cleanly. The agent can only launch the server if these work in your environment.
• When writing file paths in JSON configuration files, escape backslashes as \\ (for example, C:\\Users\\me\\workflows).
• If the server fails to start with an error stating that npx cannot be found, see Troubleshooting below.

Verifying the Connection

Try asking your agent:

If the agent invokes the catalog tool of nodecrypto and shows nodes such as symmetric-aes-encrypt, the connection is working. If the agent asks for permission the first time it calls a tool, approve it.

Usage Example

The agent typically works through the following five steps:

1. guide: Reads the authoring guide.
2. catalog: Searches for the required nodes and inspects their exact port and property definitions rather than guessing node types or port names.
3. validate: Checks the draft workflow for structural or type errors and fixes any issues.
4. run: Executes the workflow and compares the output against the expected test vector values (expect).
5. expand: Saves the verified workflow as an .ncw file and reports the saved file path.

Agents typically attach per-node memos explaining which RFC section or test vector was used and why specific parameter values were chosen, making it much easier to review the workflow on the canvas.

Saving and Opening Workflows

Where Files Are Saved

• The default output folder is nodecrypto-workflows inside your home directory (created automatically if it does not exist). The file name is derived from the workflow name with a .ncw extension.
• Changing the default folder: add --out-dir <folder> to the server arguments (e.g., "args": ["-y", "@curealls/nodecrypto", "mcp", "--out-dir", "D:\\workflows"]), or set the NODECRYPTO_OUT_DIR environment variable. If both are set, --out-dir takes precedence.
• In practice, the agent often chooses the path itself. When the agent knows the absolute path of your current project workspace, it will typically save the file there instead of the default folder. If you want it saved in the default folder, ask the agent: "Save it to the default location without specifying a path."
• Specifying a path per request: you can ask "Save it to D:\work\hmac.ncw" and the agent will save it to that exact location. Only the .ncw extension is permitted.
• Once saved, the agent reports the absolute file path. If it does not mention the path, ask: "What is the full path of the saved file?"

Overwriting Existing Files

If a file with the same name already exists, it is overwritten by default. If you do not want existing files overwritten, include "Do not overwrite if the file already exists; let me know instead" in your prompt. The agent will call expand with overwrite: false, which aborts saving and reports when the file already exists.

Opening in the Web App

1. Open the NodeCrypto web app (https://nodecrypto.dev/).
2. Click "File > Open" in the menu and select the saved .ncw file.
3. The workflow opens in a new tab. Because an opened file tab is not yet persisted to browser storage, use "Save As" if you want to keep a copy in your workspace.

The web app does not connect directly to the AI agent; the .ncw file is the bridge between the two.

Security Precautions

• Do not blindly trust a workflow generated by an agent. Inspect every node, wire connection, and parameter on the web app canvas, and verify the rationale recorded in the node memos.
• Passing an expected-value check (expect) is only meaningful if the test vector itself is authentic. Verify the source of the test vector (such as the RFC section number).
• Keep tool-call confirmation prompts enabled in your client, especially for expand, which writes files to disk and overwrites by default—verify the target path before approving.

Troubleshooting