This document covers the integration of Model Context Protocol (MCP) tools into Sim Studio's workflow execution system. MCP enables Sim to dynamically connect to external tool servers, discover available tools, and execute them within workflows using standardized JSON-RPC over HTTP.
Sim implements a full MCP client stack that connects to MCP servers (primarily via Streamable HTTP), discovers their available tools, caches tool schemas, and executes tool calls during workflow execution.
The architecture bridges high-level workflow blocks to the low-level MCP protocol via a dedicated service layer and a specialized client implementation.
Sources:
Sim uses the @modelcontextprotocol/sdk to implement the client. The primary transport supported is streamable-http, which aligns with the MCP 2025-06-18 specification.
The McpClient class manages the connection lifecycle:
StreamableHTTPClientTransport with the server URL and headers apps/sim/lib/mcp/client.ts88-92notifications/tools/list_changed to trigger cache invalidation apps/sim/lib/mcp/client.ts123-129Every tool execution requires a consent check governed by the McpSecurityPolicy apps/sim/lib/mcp/types.ts52-58 Before callTool is executed, a McpConsentRequest is generated apps/sim/lib/mcp/client.ts205-216 The client supports auditing at various levels (none, basic, detailed) apps/sim/lib/mcp/types.ts57
Sources:
MCP tools use a deterministic identifier format to route requests correctly and maintain stability across server updates.
Format: mcp-{serverId}-{toolName}
The serverId is generated deterministically using a hash of the workspaceId and the normalized serverUrl apps/sim/lib/mcp/utils.ts180-187 This ensures that if a server is deleted and re-added with the same URL, existing workflows do not break. The hash uses a variant of the djb2 algorithm to produce an 8-character hex string apps/sim/lib/mcp/utils.ts209-216
Discovery is performed via the /api/mcp/tools/discover endpoint, often triggered by the useMcpToolsQuery hook apps/sim/hooks/queries/mcp.ts104-113 It iterates through all enabled servers in a workspace, connects via McpClient, and calls listTools() apps/sim/lib/mcp/client.ts171-195
Sources:
When a workflow block triggers an MCP tool, the McpService handles the execution with specialized retry logic for session-based transports.
The service includes isSessionError detection apps/sim/lib/mcp/service.ts227-231 If a tool call fails with a session-related error (common in HTTP transports where sessions expire), the service will automatically retry the execution once after a short delay apps/sim/lib/mcp/service.ts184-222
Before sending arguments to the remote server, Sim filters out "Core Params" that are used for internal routing but are not part of the tool's actual schema. These include serverId, serverUrl, toolName, and serverName apps/sim/lib/mcp/utils.ts19-20
Sources:
Sim Studio allows exposing workflows themselves as MCP tools. This is handled by the WorkflowMcpServeAPI.
The endpoint at /api/mcp/serve/[serverId] implements the server-side of the MCP protocol apps/sim/app/api/mcp/serve/[serverId]/route.ts:123.
initialize: Returns protocol version and capabilities apps/sim/app/api/mcp/serve/[serverId]/route.ts:179-186.tools/list: Queries the workflowMcpTool table to return available workflow-tools apps/sim/app/api/mcp/serve/[serverId]/route.ts:191-192.tools/call: Triggers internal workflow execution via handleToolsCall apps/sim/app/api/mcp/serve/[serverId]/route.ts:194-202.The Serve API supports "Hybrid Auth", allowing both public access (if configured) and API Key/Session based access via checkHybridAuth apps/sim/app/api/mcp/serve/[serverId]/route.ts:133-157. It uses getUserEntityPermissions to verify workspace-level access apps/sim/app/api/mcp/serve/[serverId]/route.ts:101-105.
Sources:
To avoid expensive protocol handshakes on every UI interaction, Sim employs a multi-layered caching strategy.
McpService uses a cacheAdapter (standardized via createMcpCacheAdapter) to store server metadata and tool definitions apps/sim/lib/mcp/service.ts38-44mcpConnectionManager detects configuration changes or tool-list updates via a subscription apps/sim/lib/mcp/service.ts46-50The system enforces strict timeouts and limits to ensure stability:
Sources:
| Entity | Code Symbol | Storage / Table | Purpose |
|---|---|---|---|
| MCP Server | McpServerConfig | mcpServers | External server configuration (URL, headers) |
| Workflow Server | workflowMcpServer | workflowMcpServer | Sim's internal MCP server definition |
| MCP Tool | McpTool | workflowMcpTool | Cached tool definition and schema |
| Connection Manager | mcpConnectionManager | Memory / PubSub | Manages active connections and event propagation |
| MCP Client | McpClient | Transient | Handles the protocol-level communication |
Sources:
Refresh this wiki