MCP server (nodepilot-mcp)

A Model Context Protocol server that lets an AI agent (Claude Desktop/Code or any MCP client) control and edit NodePilot workflows and read data. Like the np CLI it is a pure HTTP client against the existing REST API — no new backend path; every tool calls an existing endpoint or computes in-process against NodePilot.Core. 116 tools across 12 groups, plus 3 MCP resources.

Agent tools

The agent group exposes list_agent_runs, get_agent_events, list_agent_mcp_servers, discover_agent_mcp_tools, save_agent_mcp_server, list_agent_skills, import_agent_skill, set_agent_skill_enabled, delete_agent_mcp_server and delete_agent_skill. Run/events use workflow read permission. Registry reads require Admin/Operator, changes Admin, and deletes the destructive-tool gate. Discovery can start a registered stdio process. Agent-client transports are separate from this stdio server.

Installation

The server is not a .NET global tool: PackAsTool cannot cope with the inherited net10.0-windows TFM (NETSDK1146), so dotnet pack fails. It is delivered through dotnet publish; the MCP client points at the resulting .exe.

# Both installers already ship the server: <install>\tools\mcp\nodepilot-mcp.exe.
# Build it yourself only from a source checkout:
dotnet publish src/NodePilot.Mcp -c Release -o C:\Tools\NodePilot-Mcp

np auth login          # the MCP server reuses this CLI session

// .mcp.json — point the client at the server
{
  "mcpServers": {
    "nodepilot": {
      "command": "C:\\Tools\\NodePilot-Mcp\\nodepilot-mcp.exe",
      "env": { "NODEPILOT_MCP_SERVER": "https://nodepilot.example.com", "NODEPILOT_MCP_PROFILE": "default" }
    }
  }
}

Configuration & authentication

Headless (started by the MCP client) → environment first, falling back to the CLI configuration/session:

Without NODEPILOT_MCP_TOKEN the server reads the np auth login session on every request, so logging in after the MCP server has started takes effect on the next tool call, without a restart.

TLS: Successful certificate validation (chain and hostname) is accepted even when a pin is also configured. If TLS validation fails, a configured SHA-256 pin decides: a match accepts the certificate, including a hostname mismatch; a mismatch rejects it even with the bypass set. Only when no pin is configured can NODEPILOT_MCP_TLS_NO_VERIFY bypass a validation error. A matching pin does not repair the name mismatch; it explicitly accepts that certificate despite it. A URL using a name on the certificate remains the normal path.

A CLI profile's pin applies only to its server origin. An invalid fingerprint format causes a repairable configuration error on tool calls (np config set tls-thumbprint <SHA256>, or none to clear it). The generic NODEPILOT_TLS_* variables are shared by CLI and MCP server.

The transport is stdio (streamable HTTP is planned as a later option). Windows only (net10.0-windows, DPAPI).

Security

• Destructive gate: delete_*, force_unlock_workflow, cancel_all_executions, restart_service and test_step are only registered with NODEPILOT_MCP_ALLOW_DESTRUCTIVE=true — otherwise they do not even appear in tools/list. get_safety_status shows the mode.
• Secrets: workflow definitions are redacted before tool output (secret/apiKey/password/ authToken/bearer/connectionString → ***). On publish/update/apply_workflow_patch, real secrets are restored by node ID from the stored version — the agent's *** never overwrites a real value. A *** on a new node or edge ID has nothing to restore, so the call is rejected and nothing is saved. The same applies to a change in a condition or case array that contains a ***; make that edit in the designer. Credentials/globals never emit secrets.
• Version check: publish_workflow/update_workflow_definition require expectedVersion, the version get_workflow_definition returned. If someone saved in between, the server answers 409 workflow_version_conflict and the newer workflow stays untouched.
• Annotations: read tools are readOnly, gated tools destructive, and enable/disable/lock are idempotent. execute_workflow is not idempotent: calling it again starts another run. Check executions before retrying a start whose response was lost.

Tool groups

• Dependencies (read-only): list_dependency_objects, get_dependencies, get_dependency_evidence. Search workflows, machines, credentials, globals and custom activities, filter by problems or missing use and sort by usage; inspect direct/indirect relationships, possible agent calls and source locations. Reports respect folder permissions, exclude secret values, and expose analysis limits and revision-bound pagination. They describe saved configuration, not predicted failures.

• Discovery: whoami, get_safety_status, list_activity_types, get_activity_config_reference, validate_cron

• Reading workflows: list_workflows, get_workflow, get_workflow_definition (redacted), get_workflow_contract, versions, export_workflow

• Editing workflows: lock/unlock/publish_workflow/update_workflow_definition, validate_workflow_definition, preview/apply_workflow_patch (merge by ID, secret protection, validate before save), create/duplicate/enable/disable/rollback/import (JSON via import_workflow, SCOrch .ois_export via import_scorch_workflow), step-test context

• Gated destructive: test_step (runs a real activity; a configuration override additionally requires edit permission and your own lock), delete/force-unlock/cancel-all

• Executions: list/get/steps/paused-steps, execute_workflow, cancel/retry/resume, trigger_external_workflow

• Telemetry: dashboard, coverage/step-health/step-stats, get_failure_causes, get_operations_graph, query_audit_log (admin), get_support_diagnostics (admin)

• Database / text2sql (admin, read-only): list_db_tables (the schema catalog; secret columns hidden, GlobalVariable.Value masked), get_db_info (provider + row/timeout limits), run_readonly_sql (one read-only statement, with the server enforcing a keyword allow-list + rollback; there is no write tool). Secret columns are unreachable through raw SQL too — a direct reference returns protected_column; wildcard projections (SELECT *, alias.*, PostgreSQL TABLE t) and serializing a whole row (to_json/row_to_json/::text/FOR JSON) of a table with a secret column return protected_row_projection; result columns with protected names are additionally masked as ***. COUNT(*) keeps working, and naming unprotected columns explicitly always works. Translating natural language into SQL is the agent's job.

• Supporting: machines, credentials, globals (secrets never emitted)

• Alerting: get_alerting_catalog (the rule vocabulary) + list/get/create/update/test_fire_alerting_rule + list_alerting_deliveries (the ledger) (+ gated delete_alerting_rule; route secrets are never emitted, webhook URLs only as scheme, host and port)

• System alerts (ADR 0008): get_system_alert_catalog + list/get/create/update/enable/disable/test_fire_system_alert_policy (+ gated delete_system_alert_policy)

• Canvas assistant (for the designer chat, largely in-process): analyze_workflow, get_available_variables, get_failure_context, find_unresolved_references, validate_edge_condition, validate_activity_config, preview_template_resolution, suggest_layout, diff_workflow_definition, get_workflow_node, check_styleguide

Resources

• nodepilot://activity-catalog — all activity/trigger types (category, isTrigger/isRemote, output parameters)
• nodepilot://activity-config-reference — curated per-activity configuration key schemas
• nodepilot://styleguide — the workflow layout style guide

The complete reference is in the repository: docs/mcp-server.md.