MCP / Claude

CntrlNode ships a Model Context Protocol (MCP) server so you can use all of its tools directly inside Claude Desktop, Claude Code, or any MCP-compatible host.

How it works

The cntrlnode-mcp binary reads JSON-RPC 2.0 messages from stdin and proxies them to a running CntrlNode server. Your AI client talks to the MCP binary; the binary talks to CntrlNode.

Claude Desktop ──stdin/stdout──▶ cntrlnode-mcp ──HTTP──▶ CntrlNode :7474

Install the MCP binary

Homebrew (macOS/Linux)

brew install meetpatell07/tap/cntrlnode
# installs both `cntrlnode` and `cntrlnode-mcp`

From GitHub Releases

# macOS arm64
curl -L https://github.com/meetpatell07/cntrlnode/releases/latest/download/cntrlnode-mcp-darwin-arm64 \
  -o /usr/local/bin/cntrlnode-mcp && chmod +x /usr/local/bin/cntrlnode-mcp

Docker image also includes the binary at /usr/local/bin/cntrlnode-mcp.

Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cntrlnode": {
      "command": "/usr/local/bin/cntrlnode-mcp",
      "env": {
        "CNTRLNODE_HOST": "localhost:7474"
      }
    }
  }
}

With API key auth enabled:

{
  "mcpServers": {
    "cntrlnode": {
      "command": "/usr/local/bin/cntrlnode-mcp",
      "env": {
        "CNTRLNODE_HOST": "localhost:7474",
        "CNTRLNODE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop after saving.

Configure Claude Code

# Add to your project's MCP config
claude mcp add cntrlnode /usr/local/bin/cntrlnode-mcp \
  --env CNTRLNODE_HOST=localhost:7474

Available tools

Once connected, Claude can use:

Tool	Description
`state_get`	Read a value from shared state
`state_set`	Write a value to shared state
`state_list`	List all keys in a workflow namespace
`task_submit`	Submit a task to an agent
`task_get`	Get task status and result
`task_cancel`	Cancel a task and its subtree
`task_tree`	View the full task delegation tree
`registry_list`	List all registered agents
`registry_discover`	Find agents by tags or natural language

Example prompts

Once Claude Desktop is connected to CntrlNode, you can ask:

"List all agents registered in CntrlNode"

"Submit a task to the researcher-1 agent with the query 'summarise Q4 results'"

"What's the current value of the 'research-results' key in workflow wf-1?"

"Cancel task 2Kx... and all its children"

Remote CntrlNode

Point the MCP binary at a remote CntrlNode instance:

{
  "env": {
    "CNTRLNODE_HOST": "cntrlnode.mycompany.internal:7474",
    "CNTRLNODE_API_KEY": "prod-key-here"
  }
}

Environment variables

Variable	Default	Description
`CNTRLNODE_HOST`	`localhost:7474`	CntrlNode server address
`CNTRLNODE_API_KEY`	(empty)	API key (if auth is enabled)