MCP Integration Block

The MCP Integration block connects your workflow to Model Context Protocol (MCP) servers, enabling automatic tool discovery, dynamic integration, and comprehensive server management. Reach for it when you want an AI agent to use tools exposed by an external MCP server (stdio, SSE, or HTTP), or when you need to test, connect, disconnect, or refresh those server connections from within a workflow.

Overview

When to Use

• Connect to an MCP server already configured in Settings > MCP and execute one of its discovered tools.
• Quickly test a new MCP server by pasting a Claude Desktop-style JSON config (mcpServers wrapper format).
• Discover and refresh the full list of tools available from a running server.
• Stand up a stdio (command-line), SSE (server-sent events), or HTTP (REST) MCP connection as part of a workflow.
• Test, connect, disconnect, or refresh a server connection without leaving the workflow canvas.
• Pass structured JSON parameters to a specific MCP tool and capture its result for downstream blocks.

Configuration

The block has two high-level modes controlled by the Use Existing Server switch. When it is on, you pick a pre-configured server and optionally execute one of its tools. When it is off, you define a brand-new server — either with a form or by pasting raw JSON.

Use Existing Server (useExistingServer)

Switch (default: off). When on, hides all new-server fields and shows the Select Server dropdown and Execute Tool controls. Configure servers permanently in Settings > MCP; use this toggle to connect to them in a workflow.

Select Server (existingServerId)

Dropdown — shown only when Use Existing Server is on. Dynamically populated from your MCP Settings. Required when the toggle is on.

Use JSON Config (useRawConfig)

Switch (default: off) — shown only when Use Existing Server is off. When on, replaces the form fields with a single JSON code editor so you can paste a config directly.

MCP Server Configuration (rawMcpConfig)

JSON code editor — shown when Use Existing Server is off AND Use JSON Config is on. Accepts the standard mcpServers wrapper format (same as Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=America/New_York"]
    }
  }
}

Required when Use JSON Config is on.

Server Name (serverName)

Short text input — shown when Use Existing Server is off AND Use JSON Config is off. A unique identifier for the new server (e.g. filesystem-server, database-connector). Required in form mode.

Connection Type (serverType)

Dropdown — shown when Use Existing Server is off AND Use JSON Config is off. Default: stdio.

Stdio fields (shown when serverType = stdio and form mode)

• Command Path (stdioCommand) — path to the MCP server executable or npx command. Required.
• Script Path/Arguments (stdioArgs) — path to the script file or additional command arguments.
• Environment Variables (stdioEnv) — key/value table of environment variables for the process.

SSE fields (shown when serverType = sse and form mode)

• SSE Endpoint URL (sseEndpoint) — full URL of the SSE endpoint (e.g. https://api.example.com/mcp/sse). Required.
• Authentication Headers (sseHeaders) — header/value table for auth or custom headers.

HTTP fields (shown when serverType = http and form mode)

• Base URL (httpBaseUrl) — base URL of the HTTP MCP server (e.g. https://api.example.com). Required.
• API Key / Token (httpApiKey) — API key or bearer token (stored as a password field).
• Custom Headers (httpHeaders) — header/value table for additional request headers.

Execute Tool (selectedTool)

Dropdown — shown only when Use Existing Server is on. Dynamically populated with tools discovered from the selected server. Leave empty to perform only a connection action.

Tool Parameters (toolParams)

JSON code editor — shown when Use Existing Server is on and a tool is selected. Parameters to pass to the chosen tool.

{
  "param1": "value1",
  "param2": "value2"
}

Connection Management (connectionAction)

Dropdown — always visible. Controls what the block does when executed. Default: test.

Advanced settings

• Connection Timeout (timeout) — slider, 5–300 seconds, step 5. Default: 30 seconds.
• Retry Attempts (retryAttempts) — slider, 0–10, step 1. Default: 3.

Inputs & Outputs

• Inputs:

  • workspaceId (string) — workspace identifier (provided automatically by execution context)
  • serverName (string) — name of the MCP server
  • serverType (string) — type of MCP connection (stdio, sse, or http)
  • config (json) — server configuration parameters (built from form fields or raw JSON)
  • rawMcpConfig (json) — raw MCP JSON configuration in Claude Desktop format
  • settings (json) — connection and behavior settings (timeout, retryAttempts)
  • execution (json) — tool execution parameters
  • action (string) — connection management action

• Outputs:

  • serverId (string) — unique server identifier
  • serverName (string) — server display name
  • connectionStatus (string) — current connection status (connected, disconnected, or error)
  • availableTools (json) — array of tools available from this server, each with id, name, description, category, inputSchema, and outputSchema
  • serverMetadata (json) — server information and statistics (type, version, lastConnected, toolCount, avgLatency)
  • executionResult (json) — result from tool execution when a tool was selected (toolName, result, success, latency, timestamp)
  • error (string) — error message if the operation failed

Tools

MCP Server Creation (mcp_create_server) — Creates and registers a new MCP server from form fields or pasted raw JSON config. Posts to /api/mcp/create-server and returns the server id, connection status, and available tools. Used when Use Existing Server is off.

MCP Server Connect (mcp_connect) — Connects to or disconnects from a pre-configured MCP server. Uses POST for connect/test and DELETE for disconnect on /api/mcp/servers/{id}/connection. Returns connection status and available tools. Used when Use Existing Server is on and no tool is selected, or when the action is disconnect.

MCP Tool Discovery (mcp_discover_tools) — Refreshes the tool catalog from a connected server. Posts to /api/mcp/discover-tools and returns availableTools along with discovery statistics (toolsFound, categoriesFound, lastUpdated). Used when the connection action is refresh.

MCP Tool Execution (mcp_execute_tool) — Executes a named tool on a connected server with the supplied JSON parameters. Posts to /api/mcp/execute-tool and returns the executionResult (result data, latency, timestamp) and toolMetadata. Used when Use Existing Server is on and a tool is selected.

YAML Example

mcp_1:
  type: mcp
  name: "MCP Integration"
  inputs:
    useExistingServer: true
    existingServerId: "filesystem-server"
    selectedTool: "read_file"
    toolParams: |
      {
        "path": "/data/notes.txt"
      }
    connectionAction: "connect"
  connections:
    outgoing:
      - target: agent_1