Skip to main content

Connect

Establishes connections to one or more MCP servers using a JSON configuration. This is the entry point for all MCP client operations, enabling your automation to interact with MCP servers.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs​

  • MCP Servers - JSON configuration defining one or more MCP servers to connect to. Uses the MCP configuration format with server commands, arguments, and environment variables.

Options​

  • Working Directory - Working directory for the MCP server processes. Optional, defaults to the current directory.

Outputs​

  • Client Id - The ID of the first successfully connected server. Use this with subsequent MCP client nodes.
  • Clients - Array of all successfully connected client IDs. Useful when connecting to multiple servers.

How It Works​

The Connect node establishes connections to MCP servers:

  1. Configuration Parsing - Parses the JSON configuration to extract server definitions
  2. Server Initialization - For each server in the configuration:
    • Creates a stdio-based MCP client with the specified command and arguments
    • Applies environment variables if provided
    • Initializes the connection with protocol version 1.0
    • Performs MCP handshake
  3. Client Registration - Stores successful connections in a global registry
  4. Output Generation - Returns client IDs for use in subsequent nodes
  5. Error Handling - Continues with other servers if one fails, reports all errors

Configuration Format​

The MCP Servers input uses this JSON structure:

{
  "mcpServers": {
    "server_name": {
      "command": "executable_path",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Fields:

  • server_name - Unique identifier for the server (becomes the Client ID)
  • command - Path to the executable or command to run
  • args - Array of command-line arguments (optional)
  • env - Environment variables for the server process (optional)

Requirements​

  • Valid MCP server configuration in JSON format
  • Executable specified in command must exist and be accessible
  • Server must implement the MCP protocol
  • Network connectivity for stdio communication

Usage Notes​

Connection Lifecycle​

  • Connections are established when the Connect node executes
  • Connections remain active until the flow stops or OnClose is called
  • Each execution creates new connections (doesn't reuse existing ones by default)
  • Proper cleanup is performed when the flow ends

Multiple Servers​

  • You can connect to multiple MCP servers in one Connect node
  • Each server gets a unique Client ID (the server name from config)
  • Use Client Id output for the first server, or Clients array for specific servers
  • If any server fails, others continue (partial success is possible)

Client ID Usage​

  • The Client ID is used by all subsequent MCP client nodes
  • It identifies which MCP server to interact with
  • Store the Client ID in a variable if needed across multiple operations

Examples​

Example 1: Connect to Local MCP Server​

MCP Servers Configuration:

{
  "mcpServers": {
    "local-server": {
      "command": "node",
      "args": ["/path/to/mcp-server.js"]
    }
  }
}

Outputs:

  • Client Id: local-server
  • Clients: ["local-server"]

Use Case: Connect to a Node.js-based MCP server running locally.

Example 2: Connect to Python MCP Server with Environment​

MCP Servers Configuration:

{
  "mcpServers": {
    "python-tools": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "env": {
        "API_KEY": "your-api-key",
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    }
  }
}

Working Directory: /path/to/project

Use Case: Connect to Python MCP server with API credentials and database configuration.

Example 3: Multiple MCP Servers​

MCP Servers Configuration:

{
  "mcpServers": {
    "weather-api": {
      "command": "node",
      "args": ["./servers/weather.js"]
    },
    "database-tools": {
      "command": "python",
      "args": ["-m", "db_mcp_server"]
    },
    "file-system": {
      "command": "./mcp-fs-server",
      "args": ["--root", "/data"]
    }
  }
}

Outputs:

  • Client Id: weather-api (first server)
  • Clients: ["weather-api", "database-tools", "file-system"]

Use Case: Connect to multiple specialized MCP servers for different capabilities.

Example 4: Filesystem MCP Server​

MCP Servers Configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    }
  }
}

Use Case: Connect to the official MCP filesystem server for file operations.

Example 5: Custom Binary with Args​

MCP Servers Configuration:

{
  "mcpServers": {
    "custom-server": {
      "command": "/usr/local/bin/my-mcp-server",
      "args": [
        "--port", "8080",
        "--config", "/etc/mcp/config.json",
        "--verbose"
      ],
      "env": {
        "LOG_LEVEL": "debug",
        "CACHE_DIR": "/var/cache/mcp"
      }
    }
  }
}

Best Practices​

  1. Server Naming:

    • Use descriptive server names (e.g., weather-api, database-tools)
    • Use lowercase with hyphens for consistency
    • Names should indicate the server's purpose

  2. Configuration Management:

    • Store server configurations in Vault for security
    • Use environment variables for sensitive data
    • Keep configurations in version control (without secrets)

  3. Error Handling:

    • Always check if connection succeeded before using Client ID
    • Handle partial failures when connecting to multiple servers
    • Log connection errors for debugging

  4. Resource Management:

    • Connections are cleaned up automatically on flow stop
    • Avoid creating unnecessary connections
    • Reuse Client IDs across multiple operations

  5. Security:

    • Don't hardcode API keys or credentials in configurations
    • Use environment variables for sensitive data
    • Validate executable paths to prevent command injection
    • Restrict file system access when appropriate

  6. Testing:

    • Test connections with simple servers first
    • Verify command paths and arguments
    • Check environment variables are properly set
    • Test error scenarios (invalid command, timeout, etc.)

Common Errors and Solutions​

Error: "No MCP servers configured or connected"​

Cause: All server connections failed or configuration is empty.

Solution:

  • Verify JSON configuration syntax is correct
  • Check command paths are valid and executable
  • Ensure servers are properly installed
  • Check server logs for initialization errors
  • Test server command manually in terminal

Error: "Failed to create MCP client"​

Cause: Unable to start the MCP server process.

Solution:

  • Verify command exists and is executable
  • Check file permissions on the executable
  • Ensure all required dependencies are installed
  • Verify working directory is correct

Error: "Failed to initialize"​

Cause: MCP handshake failed with the server.

Solution:

  • Verify server implements MCP protocol correctly
  • Check server is outputting to stdio properly
  • Increase initialization timeout if needed
  • Check server logs for initialization errors

Error: "Command not found"​

Cause: Executable specified in command doesn't exist.

Solution:

  • Use absolute paths for executables
  • Verify command is in system PATH
  • Check spelling and capitalization
  • Test command in terminal first

Tips for Effective Use​

  1. Start Simple - Connect to one server first, then add more
  2. Test Commands - Verify commands work in terminal before using in Connect
  3. Use Absolute Paths - Avoid PATH issues by using full executable paths
  4. Environment Setup - Ensure all required environment variables are set
  5. Error Logging - Enable verbose logging during development
  6. Connection Reuse - Store Client ID for reuse across multiple operations
  7. Timeout Handling - Be patient during initial connection (60s default)
  8. Validate Early - Check Client ID is valid before subsequent operations

Configuration Examples​

Node.js Server (NPM Package)​

{
  "mcpServers": {
    "npm-server": {
      "command": "npx",
      "args": ["-y", "@scope/mcp-server-package"]
    }
  }
}

Python Server (Module)​

{
  "mcpServers": {
    "python-server": {
      "command": "python",
      "args": ["-m", "my_mcp_module"]
    }
  }
}

Binary Executable​

{
  "mcpServers": {
    "binary-server": {
      "command": "/usr/local/bin/mcp-server",
      "args": ["--config", "/etc/mcp.conf"]
    }
  }
}

Docker Container​

{
  "mcpServers": {
    "docker-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "my-mcp-image:latest"
      ]
    }
  }
}

With Environment Variables​

{
  "mcpServers": {
    "api-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "NODE_ENV": "production",
        "API_KEY": "${VAULT:mcp_api_key}",
        "PORT": "3000"
      }
    }
  }
}