Custom Tools & MCP

Relevant source files

• apps/sim/app/api/billing/update-cost/route.ts
• apps/sim/app/api/mcp/events/route.test.ts
• apps/sim/app/api/mcp/serve/[serverId]/route.ts
• apps/sim/app/api/mcp/servers/[id]/refresh/route.ts
• apps/sim/app/api/mcp/servers/[id]/route.ts
• apps/sim/app/api/mcp/servers/route.ts
• apps/sim/app/api/mcp/servers/test-connection/route.ts
• apps/sim/app/api/mcp/tools/stored/route.ts
• apps/sim/app/api/mcp/workflow-servers/[id]/route.ts
• apps/sim/app/api/mcp/workflow-servers/[id]/tools/[toolId]/route.ts
• apps/sim/app/api/mcp/workflow-servers/[id]/tools/route.ts
• apps/sim/app/api/mcp/workflow-servers/route.ts
• apps/sim/app/api/settings/allowed-mcp-domains/route.ts
• apps/sim/app/api/wand/route.ts
• apps/sim/app/api/workflows/[id]/log/route.ts
• apps/sim/app/workspace/[workspaceId]/settings/components/credential-sets/credential-sets.tsx
• apps/sim/app/workspace/[workspaceId]/settings/components/inbox/inbox.tsx
• apps/sim/app/workspace/[workspaceId]/settings/components/team-management/team-management.tsx
• apps/sim/ee/sso/components/sso-settings.tsx
• apps/sim/executor/utils/output-filter.ts
• apps/sim/hooks/queries/mcp.ts
• apps/sim/lib/billing/core/usage-log.ts
• apps/sim/lib/logs/execution/logger.test.ts
• apps/sim/lib/logs/execution/logger.ts
• apps/sim/lib/logs/execution/logging-factory.ts
• apps/sim/lib/logs/execution/logging-session.ts
• apps/sim/lib/logs/types.ts
• apps/sim/lib/mcp/client.ts
• apps/sim/lib/mcp/connection-manager.test.ts
• apps/sim/lib/mcp/domain-check.test.ts
• apps/sim/lib/mcp/domain-check.ts
• apps/sim/lib/mcp/pubsub.test.ts
• apps/sim/lib/mcp/service.ts
• apps/sim/lib/mcp/shared.ts
• apps/sim/lib/mcp/types.ts
• apps/sim/lib/mcp/utils.test.ts
• apps/sim/lib/mcp/utils.ts
• apps/sim/tools/hubspot/list_lists.ts
• apps/sim/tools/index.test.ts
• apps/sim/tools/index.ts
• apps/sim/tools/perplexity/chat.ts
• apps/sim/tools/types.ts

This document covers the system for extending Sim with custom-defined tools and Model Context Protocol (MCP) integrations. It explains how users create custom JavaScript tools, how MCP servers are connected for external tool discovery, and how both types integrate into the unified tool execution framework.

For information about built-in tools and the core tool registry, see Tool Registry System. For details on how agents select and invoke tools, see Agent Block.

---

System Overview

Sim supports three categories of tools for workflow execution:

Tool Type	Description	Discovery Method	Execution Path
Built-in	200+ pre-defined integrations	Static registry	Direct HTTP or directExecution
Custom	User-defined functions	Database (custom_tools table)	/api/function/execute with VM isolation
MCP	External tools via protocol	Runtime discovery	/api/mcp/serve/[serverId] with server proxy

All types conform to the ToolConfig interface apps/sim/tools/types.ts85-178 and are executed through the unified executeTool function apps/sim/tools/index.ts251-500

Sources: apps/sim/tools/index.ts16-34 apps/sim/lib/mcp/service.ts174-222

---

Custom Tools Architecture

Code Execution Environment

Custom tools execute code in a secure, sandboxed environment. The system supports execution engines based on code requirements:

1. Isolated VM: For standard JavaScript without external imports. This uses the isolated-vm library for high-performance local sandboxing.
2. E2B Sandbox: For Python code or JavaScript requiring external npm modules or complex system dependencies.

Function Execution Pipeline

The diagram below bridges the user's intent to the underlying execution entities.

Title: Custom Tool Execution Flow

Sources: apps/sim/app/api/wand/route.ts159-221 apps/sim/tools/index.ts251-300 apps/sim/tools/index.test.ts119-146

Security & Validation

To prevent VM escapes and SSRF, the execution pipeline implements several layers of protection:

• Hosted Key Injection: If a tool requires an API key, the system can inject hosted keys via injectHostedKeyIfNeeded apps/sim/tools/index.ts49-137
• SSRF Protection: URL validation blocks internal IP ranges via validateUrlWithDNS apps/sim/tools/index.ts8-10
• Rate Limiting: Execution is governed by getHostedKeyRateLimiter to prevent abuse apps/sim/tools/index.ts81-117

For details, see Custom Tool Creation.

---

MCP Integration

MCP Server Discovery & Management

Sim implements the Model Context Protocol (MCP) to allow workflows to interact with external tool servers. The McpService manages the lifecycle of these connections apps/sim/lib/mcp/service.ts37-51

• Transport: Supports streamable-http (MCP 2025-06-18) and protocol versions back to 2024-11-05 apps/sim/lib/mcp/client.ts47-51
• Caching: Discovery results (tools, schemas) are cached using a McpCacheStorageAdapter with a timeout defined in MCP_CONSTANTS.CACHE_TIMEOUT apps/sim/lib/mcp/service.ts38-40
• SSRF Validation: MCP server URLs are validated against allowed domains via isMcpDomainAllowed apps/sim/lib/mcp/service.ts103-105

MCP Tool Execution Flow

This diagram illustrates how a natural language request is proxied through the MCP service to an external provider.

Title: MCP Proxy Architecture

Sources: apps/sim/lib/mcp/service.ts174-222 apps/sim/lib/mcp/client.ts200-240 apps/sim/app/api/mcp/serve/[serverId]/route.ts:123-202

For details, see MCP Tool Integration.

---

Parameter Schemas & Enrichment

Tool Parameter Schemas

Tools define their inputs using a structured schema that determines visibility and validation rules.

• Visibility: Parameters can be user-or-llm, user-only, llm-only, or hidden apps/sim/tools/types.ts54-59
• Types: Supports string, number, boolean, json, file, array, and object apps/sim/tools/types.ts32-40

For details, see Tool Parameter Schemas.

Dynamic Schema Enrichment

At runtime, tool schemas can be enriched based on the execution context.

• SchemaEnrichmentConfig: Allows fetching dynamic schemas based on a dependency (e.g., fetching a specific Table's columns) apps/sim/tools/types.ts210-220
• ToolEnrichmentConfig: Modifies the entire tool description and all parameters based on runtime values apps/sim/tools/types.ts226-237

Sources: apps/sim/tools/types.ts206-237 apps/sim/tools/index.ts17-34

For details, see Dynamic Schema Enrichment.