MCP Tool

Defines a tool that AI clients (Claude Desktop, Claude Code, Cursor) can discover and call over MCP, and starts this flow each time the AI calls it.

Inputs

This node has no input — like HTTP In, it is where the flow starts. It runs when an AI client calls the tool.

Outputs

payload object

Arguments provided by the AI, already checked against the inputs defined here: {input1: value1, input2: value2}

ch.mcp.request object

Internal tracking info (keep it on the message — MCP Response reads it):

• toolName - Tool name
• arguments - Arguments from the AI
• requestId - Unique request ID for concurrency
• toolNodeId - Node ID for MCP Response
• workflowId - Workflow serving the tool
• startedAt - Call start time (ISO-8601, UTC)

Details

The MCP Tool node is the bridge between AI clients and your workflow. It:

1. Publishes a tool definition when the workflow is deployed
2. When the AI calls the tool, checks the arguments and starts your flow
3. Waits for MCP Response to return the result to the AI

Tool Definition

Tool name

Unique within the workflow (letters, numbers, underscores, hyphens; max 64). AI uses this to call the tool. A duplicate name is shown as an error and not published.

Description

Tell the AI what this tool does and when to use it. Be specific—AI uses this to decide when to call it.

Inputs

Define what arguments the AI should provide:

• name: Input identifier
• type: string, number, boolean, object, array
• description: Help AI understand what value to provide
• required: Whether this input is mandatory

A call with a missing required input or a wrong type is refused with an error naming the input, and the flow does not run.

Tool Settings

Timeout

Max milliseconds to wait for MCP Response. Default: 30000 (30 seconds). After that the AI gets a timeout error.

Validation Code

Optional JavaScript run after the input checks, before the flow starts:

if (!/^SYN-\d+$/.test(input.patientId)) {
  return { valid: false, error: 'patientId must look like SYN-123' };
}
return { valid: true };

A rejection is sent to the AI as Invalid input: … and the flow does not run. If the code itself has an error, the node shows it and the tool is not published until it is fixed.

MCP URL

Shown in the edit dialog: /api/workflow/<workflowId>/mcp/exec. Every MCP Tool node in the workflow is served from this one URL. Removing the node or disabling the workflow removes the tool.

Authentication

Every request must carry a ConnectHealth API key in the x-api-key header. A missing, invalid or disabled key is rejected before anything runs. Disabling the key in Settings → API Keys removes access immediately.

Examples

Allergy Lookup Tool:

Tool name: get_allergies
Description: Returns the allergies recorded for a patient
Inputs:
  - patientId (string, required)
    "The patient's FHIR id"

Patient Search Tool:

Tool name: search_patient
Description: Search for patients by name or MRN
Inputs:
  - searchTerm (string, required)
  - limit (number, optional)

Connecting Claude Code:

claude mcp add --transport http connecthealth \
  https://<host>/api/workflow/<workflowId>/mcp/exec \
  --header "x-api-key: <YOUR_API_KEY>"

Flow Pattern

[MCP Tool] → [Your Tool Flow] → [MCP Response]
                 ↘ on error → [Catch] → [MCP Response]

Best Practices

• Write clear, specific tool descriptions
• Mark only truly required inputs as required
• Validate inputs to prevent errors downstream
• Always end tool flows with MCP Response
• Wire a Catch node to MCP Response so failures reach the AI as errors, not timeouts
• Give each AI client its own API key, so one can be disabled without affecting others