Skip to main content

Workflows as MCP tools

MCP (Model Context Protocol) lets an AI client discover and call tools. An Intellectible workflow can provide those tools: you define what each tool does, the arguments it accepts, and the result it returns.

For example, expose find_customer or summarise_document instead of asking an external AI client to understand your database and processing steps. The client sees a tool interface; the workflow contains the logic behind it.

Build the server definition​

Use these nodes to define what the client can discover:

  1. Add MCP Server, configure its server details, and define its tools. Give each tool a clear name, description, and input schema.
  2. Add MCP Server Start, which fires when the endpoint requests the server definition.
  3. Connect MCP Server Start's fired event to Set MCP Output's set input.
  4. Connect MCP Server's output data to that Set MCP Output node's value input.

MCP Server is a data-producing node. It supplies the configuration; it does not need an event input. MCP Server Start is the event trigger for this path, not the ordinary Start node.

Handle a tool call​

Create a separate execution path for each tool:

  1. Add MCP Server Tool Call Event, setting its Name to exactly the tool name in the server definition.
  2. Add named Input nodes matching the tool's argument names.
  3. Connect the tool event's fired output to the first action, and pass the Input values to the nodes that use them.
  4. At the end, trigger Set MCP Output and supply the tool result as its value.

For a tool named find_customer with an email argument, the event node listens for find_customer and an Input named email supplies the lookup value. The tool definition and event handler must use exactly the same name.

Keep the server-definition and tool-call paths distinct. Discovering tools should return configuration, not send messages, change records, or carry out the tool's business action.

Connect an MCP client​

Configure an MCP client that supports Streamable HTTP with:

{API_BASE}/projects/{projectId}/workflows/{workflowId}/mcp

Use your environment's public API base URL. Configure the client's Authorization header with a raw project API key that has workflows.run permission for this workflow, without a Bearer prefix. The client needs to support supplying that header; its configuration format depends on the client.

Ask the client to discover the tools, then make a safe test call. Check that the declared arguments reach the workflow and that the response contains the intended result. Object results are JSON-encoded in the MCP text response.

The normal editor Run action does not simulate MCP discovery or a tool call. Test with an MCP client and inspect Logs → API in the workflow. If no tools appear, check the server-definition output; if a particular tool does not execute, check the exact tool name and its event path.

Keep tools focused and safe​

Use precise descriptions and schemas so the client knows when and how to call each tool. Validate arguments before acting, limit the key's permissions, and avoid returning secrets or unnecessary personal information. For tools that write data or contact people, configure appropriate confirmation behaviour in the calling client.

See the MCP endpoint reference for protocol details and the API guide for ordinary application calls.