Node-RED MCP Server Integration

A comprehensive skill for integrating Model Context Protocol (MCP) servers with Node-RED, providing standardized AI agent tool interfaces, server lifecycle management, and real-time communication capabilities.

What This Skill Does

This skill enables you to work with the `node-red-contrib-mcp-server` package, which provides three core Node-RED nodes for complete MCP server integration:

1. **MCP Server Node**: Manage MCP server processes (start, stop, monitor)

2. **MCP Client Node**: Connect to and communicate with MCP servers

3. **MCP Tool Node**: Invoke specific MCP tools directly from flows

The package supports HTTP, Server-Sent Events (SSE), and WebSocket connections, with built-in health monitoring, automatic restarts, and visual MCP server creation entirely within Node-RED.

Installation

Step 1: Install the Package

Guide the user through installation:

```bash

cd ~/.node-red

npm install node-red-contrib-mcp-server

```

For local development:

```bash

npm link

cd ~/.node-red

npm link node-red-contrib-mcp-server

```

Step 2: Restart Node-RED

The nodes will appear in the Node-RED palette after restart.

Working with MCP Server Node

Configuration Parameters

When helping users configure MCP Server nodes:

Input Commands

Send messages with these topics to control the server:

```javascript

// Start server

msg.topic = "start";

// Stop server

msg.topic = "stop";

// Restart server

msg.topic = "restart";

// Get status

msg.topic = "status";

```

Output Topics

Monitor server events:

Working with MCP Client Node

Configuration Parameters

Input Commands

```javascript

// Connect to server

msg.topic = "connect";

// Disconnect

msg.topic = "disconnect";

// Send MCP request

msg.topic = "request";

msg.payload = {

method: "add_todo_tool",

params: {

description: "Task description",

project: "ProjectName"

}

};

// Get connection status

msg.topic = "status";

```

Output Topics

Working with MCP Tool Node

Configuration Parameters

- "Result Only": Extract result from MCP response

- "Full Response": Complete MCP JSON-RPC response

- "Custom": Preserve original message, add response

Parameter Override Priority

Parameters are resolved in this order (highest to lowest priority):

1. Message-specific properties (`msg.description`, `msg.project`, etc.)

2. `msg.payload.params` object

3. `msg.payload` (if object without method property)

4. Default parameters from node configuration

Example Tool Invocations

```javascript

// Method 1: Direct properties

msg.description = "New task from Node-RED";

msg.project = "MyProject";

msg.priority = "High";

// Method 2: Params object

msg.payload = {

params: {

description: "New task",

project: "MyProject"

}

};

// Method 3: Direct payload (merged with defaults)

msg.payload = {

description: "New task",

project: "MyProject"

};

```

Using Example Flows

The package includes two comprehensive example flows:

External MCP Server Example

Location: `examples/external-mcp-server-example.json`

Shows:

Import steps:

1. Node-RED Menu (☰) → Import

2. Select file: `external-mcp-server-example.json`

3. Deploy and watch debug output

Flow-Based MCP Server Example

Location: `examples/flow-based-mcp-server-example.json`

Shows:

Omnispindle Integration

The package includes built-in Omnispindle MCP server support with preset configurations.

Available Omnispindle Tools

Quick Setup

1. Click "Load Omnispindle Preset" in node configuration

2. Automatically configures for local Omnispindle server

3. Sets appropriate connection types and parameters

Common Flow Patterns

Health Monitoring Flow

```javascript

// Connect server output to function node

if (msg.topic === "stdout" && msg.payload.includes("error")) {

return {topic: "alert", payload: "Server error detected"};

}

if (msg.topic === "exit" && msg.payload.code !== 0) {

return {topic: "restart", payload: {}};

}

```

Dynamic Tool Discovery

```javascript

// Get available tools

msg.topic = "request";

msg.payload = {

method: "tools/list",

params: {}

};

// Process response to populate UI or routing

```

Connection Failover

```javascript

// Handle connection errors with backup server

if (msg.topic === "error") {

msg.topic = "connect";

msg.payload = {serverUrl: "http://backup:8000"};

return msg;

}

```

Troubleshooting Guide

Server Won't Start

Check these common issues:

1. Verify server path exists and is executable

2. Confirm Python/Node.js environment is correct

3. Check if port is already in use

4. Review server arguments syntax

5. Check Node-RED debug logs

Connection Issues

1. Verify server is running (`curl http://localhost:8000/health`)

2. Check firewall settings

3. Confirm correct URL format and port

4. Test connection type (try HTTP first, then SSE/WebSocket)

Tool Calls Fail

1. Verify server supports the requested tool (use `tools/list`)

2. Validate parameter JSON syntax

3. Check server logs for detailed errors

4. Verify required parameters are provided

Performance Issues

1. Adjust health check intervals in server node

2. Configure appropriate timeouts

3. Use connection pooling for high-volume scenarios

4. Monitor server resource usage (CPU, memory)

API Endpoints

The package exposes HTTP endpoints:

Requirements

Best Practices

1. **Always enable health checks** for production MCP servers

2. **Use auto-restart** for critical services

3. **Monitor stdout/stderr** outputs for debugging

4. **Set appropriate timeouts** based on tool complexity

5. **Use SSE or WebSocket** for real-time applications

6. **Configure environment variables** in server node, not in command args

7. **Test with HTTP first** before switching to streaming protocols

8. **Use default parameters** in Tool nodes for common values

9. **Handle connection errors** with retry logic

10. **Log all MCP responses** during development

Related Resources

When to Use This Skill

Use this skill when: