update(docs): update mcp, custom tools, and variables docs

apps/docs/content/docs/en/custom-tools/index.mdx

@@ -0,0 +1,84 @@
+---
+title: Custom Tools
+description: Extend your agents with your own functions — defined by a schema and executed as JavaScript
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+
+Custom Tools let you define your own functions that agents can call, without needing an external MCP server. You write a JSON schema describing the function and the JavaScript code that runs when the agent invokes it.
+
+## What Is a Custom Tool?
+
+A custom tool has three parts:
+
+| Part | Description |
+|------|-------------|
+| **Schema** | OpenAI function-calling format — name, description, and parameters. This is what the agent sees when deciding whether to call the tool. |
+| **Code** | JavaScript that runs when the tool is called. Parameters come in as variables matching the schema. |
+| **Scope** | Custom tools are workspace-scoped and available to every agent in that workspace. |
+
+Use custom tools when you need tightly-scoped logic that doesn't warrant spinning up a full MCP server — one-off API calls, formatting helpers, internal utilities, etc.
+
+## Creating a Custom Tool
+
+1. Navigate to **Settings → Custom Tools**
+2. Click **Add**
+3. Fill out the **Schema** tab with your function definition
+4. Write your implementation in the **Code** tab
+5. Click **Save**
+
+<Callout type="info">
+You can also create a custom tool directly from an Agent block — click **Add tool… → Create Tool** in the tool dropdown. The schema editor has an AI-generation option that drafts the schema from a plain-English description.
+</Callout>
+
+## Schema Format
+
+Custom tool schemas follow the OpenAI function-calling spec:
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "get_weather",
+    "description": "Get the current weather for a city",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "city": {
+          "type": "string",
+          "description": "The city to get weather for"
+        }
+      },
+      "required": ["city"]
+    }
+  }
+}
+```
+
+The `name` must be lowercase, use underscores, and match what your code expects as input.
+
+## Using Custom Tools in Agents
+
+Once created, your tools become available in any Agent block:
+
+1. Open an **Agent** block
+2. In the **Tools** section, click **Add tool…**
+3. Under **Custom Tools**, click the tool you want to add
+4. The agent can now call the tool the same way it calls MCP tools or built-in tools
+
+## Custom Tools vs MCP Tools
+
+| | **Custom Tools** | **MCP Tools** |
+|---|---|---|
+| **Defined** | Inline — schema + code in Sim | External MCP server |
+| **Hosting** | Runs inside Sim | Runs on your server |
+| **Best for** | Small, workspace-specific helpers | Shared tools, third-party services, complex integrations |
+| **Setup** | One modal | Deploy and register a server |
+
+## Permission Requirements
+
+| Action | Required Permission |
+|--------|-------------------|
+| Create or update custom tools | **Write** or **Admin** |
+| Delete custom tools | **Admin** |
+| Use custom tools in agents | **Read**, **Write**, or **Admin** |

apps/docs/content/docs/en/mcp/deploy-workflows.mdx

@@ -3,6 +3,7 @@ title: Deploy Workflows as MCP
 description: Expose your workflows as MCP tools for external AI assistants and applications
 ---
 
+import { Image } from '@/components/ui/image'
 import { Video } from '@/components/ui/video'
 import { Callout } from 'fumadocs-ui/components/callout'
 import { FAQ } from '@/components/ui/faq'
@@ -18,10 +19,45 @@ MCP servers group your workflow tools together. Create and manage them in worksp
 </div>
 
 1. Navigate to **Settings → MCP Servers**
-2. Click **Create Server**
+
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/mcp-servers-settings.png"
+    alt="MCP Servers settings page"
+    width={700}
+    height={450}
+    className="my-6"
+  />
+</div>
+
+2. Click **Add**
 3. Enter a name and optional description
-4. Copy the server URL for use in your MCP clients
-5. View and manage all tools added to the server
+
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/mcp-server-add-modal.png"
+    alt="Add New MCP Server modal"
+    width={550}
+    height={380}
+    className="my-6"
+  />
+</div>
+
+4. Click **Add Server**
+5. Click **Details** to view the MCP server
+
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/mcp-server-details.png"
+    alt="MCP Server details view"
+    width={700}
+    height={450}
+    className="my-6"
+  />
+</div>
+
+6. Copy the server URL for use in your MCP clients
+7. View and manage all tools added to the server
 
 ## Adding a Workflow as a Tool
 
@@ -33,9 +69,21 @@ Once your workflow is deployed, you can expose it as an MCP tool:
 
 1. Open your deployed workflow
 2. Click **Deploy** and go to the **MCP** tab
+
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/mcp-deploy-modal.png"
+    alt="Workflow Deployment MCP tab"
+    width={380}
+    height={470}
+    className="my-6"
+  />
+</div>
+
 3. Configure the tool name and description
 4. Add descriptions for each parameter (helps AI understand inputs)
 5. Select which MCP servers to add it to
+6. Click **Save Tool**
 
 <Callout type="info">
 The workflow must be deployed before it can be added as an MCP tool.
@@ -54,27 +102,25 @@ Your workflow's input format fields become tool parameters. Add descriptions to
 
 ## Connecting MCP Clients
 
-Use the server URL from settings to connect external applications:
-
-### Claude Desktop
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+Sim generates a ready-to-paste configuration for every supported client. To get it:
 
-```json
-{
-  "mcpServers": {
-    "my-sim-workflows": {
-      "command": "npx",
-      "args": ["-y", "mcp-remote", "YOUR_SERVER_URL"]
-    }
-  }
-}
-```
-
-### Cursor
-Add the server URL in Cursor's MCP settings using the same mcp-remote pattern.
+1. Navigate to **Settings → MCP Servers**
+2. Click **Details** on your server
+3. Under **MCP Client**, select your client — **Cursor**, **Claude Code**, **Claude Desktop**, **VS Code**, or **Sim**
+4. Copy the configuration, replacing `$SIM_API_KEY` with your Sim API key
+
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/mcp-client-config.png"
+    alt="MCP client configuration panel"
+    width={700}
+    height={450}
+    className="my-6"
+  />
+</div>
 
 <Callout type="warn">
-Include your API key header (`X-API-Key`) for authenticated access when using mcp-remote or other HTTP-based MCP transports.
+Every request must include the `X-API-Key` header for authenticated access.
 </Callout>
 
 ## Server Management

apps/docs/content/docs/en/mcp/index.mdx

@@ -18,35 +18,58 @@ MCP is an open standard that enables AI assistants to securely connect to extern
 - Execute custom tools and scripts
 - Maintain secure, controlled access to external resources
 
-## Configuring MCP Servers
+## Adding an MCP Server as a Tool
 
-MCP servers provide collections of tools that your agents can use. Configure them in workspace settings:
+MCP servers provide collections of tools that your agents can use.
 
 <div className="mx-auto w-full overflow-hidden rounded-lg">
   <Video src="mcp/settings-mcp-tools.mp4" width={700} height={450} />
 </div>
 
-1. Navigate to your workspace settings
-2. Go to the **MCP Servers** section
-3. Click **Add MCP Server**
-4. Enter the server configuration details
-5. Save the configuration
+To add one:
+
+1. Navigate to **Settings → MCP Tools**
+
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/mcp-settings.png"
+    alt="MCP Tools settings page"
+    width={700}
+    height={450}
+    className="my-6"
+  />
+</div>
+
+2. Click **Add** to open the configuration modal
+3. Enter a **Server Name** and **Server URL**
+4. Add any required **Headers** (e.g. API keys)
+5. Click **Add MCP** to save
+
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/mcp-add-modal.png"
+    alt="Add New MCP Server modal"
+    width={450}
+    height={290}
+    className="my-6"
+  />
+</div>
 
 <Callout type="info">
 You can also configure MCP servers directly from the toolbar in an Agent block for quick setup.
 </Callout>
 
 ### Refresh Tools
 
-Click **Refresh** on a server to fetch the latest tool schemas and automatically update any agent blocks using those tools with the new parameter definitions.
+To auto-refresh an MCP tool already in use by an agent, go to **Settings → MCP Tools**, open the server's details, and click **Refresh**. This fetches the latest tool schemas and automatically updates any agent blocks using those tools with the new parameter definitions.
 
 ## Using MCP Tools in Agents
 
 Once MCP servers are configured, their tools become available within your agent blocks:
 
 <div className="flex justify-center">
   <Image
-    src="/static/blocks/mcp-2.png"
+    src="/static/blocks/mcp-agent-dropdown.png"
     alt="Using MCP Tool in Agent Block"
     width={700}
     height={450}
@@ -55,17 +78,33 @@ Once MCP servers are configured, their tools become available within your agent
 </div>
 
 1. Open an **Agent** block
-2. In the **Tools** section, you'll see available MCP tools
-3. Select the tools you want the agent to use
-4. The agent can now access these tools during execution
+2. In the **Tools** section, click **Add tool…**
+3. Under **MCP Servers**, click a server to see its tools
+
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/mcp-agent-tools.png"
+    alt="MCP tools list for a selected server"
+    width={400}
+    height={400}
+    className="my-6"
+  />
+</div>
+
+4. Select individual tools, or choose **Use all N tools** to add every tool from that server
+5. The agent can now access these tools during execution
+
+<Callout type="info">
+If you haven't configured a server yet, click **Add MCP Server** at the top of the dropdown to open the setup modal without leaving the block.
+</Callout>
 
 ## Standalone MCP Tool Block
 
 For more granular control, you can use the dedicated MCP Tool block to execute specific MCP tools:
 
 <div className="flex justify-center">
   <Image
-    src="/static/blocks/mcp-3.png"
+    src="/static/blocks/mcp-tool-block.png"
     alt="Standalone MCP Tool Block"
     width={700}
     height={450}
@@ -79,17 +118,14 @@ The MCP Tool block allows you to:
 - Use the tool's output in subsequent workflow steps
 - Chain multiple MCP tools together
 
-### When to Use MCP Tool vs Agent
-
-**Use Agent with MCP tools when:**
-- You want the AI to decide which tools to use
-- You need complex reasoning about when and how to use tools
-- You want natural language interaction with the tools
+## When to Use MCP Tool vs Agent
 
-**Use MCP Tool block when:**
-- You need deterministic tool execution
-- You want to execute a specific tool with known parameters
-- You're building structured workflows with predictable steps
+| | **Agent with MCP tools** | **MCP Tool block** |
+|---|---|---|
+| **Execution** | AI decides which tools to call | Deterministic — runs the tool you pick |
+| **Parameters** | AI chooses at runtime | You set them explicitly |
+| **Best for** | Dynamic, conversational flows | Structured, repeatable steps |
+| **Reasoning** | Handles complex multi-step logic | One tool, one call |
 
 ## Permission Requirements
 

apps/docs/content/docs/en/meta.json

@@ -12,6 +12,7 @@
     "connections",
     "---Features---",
     "mcp",
+    "custom-tools",
     "copilot",
     "mailer",
     "skills",