Using MCP tools
The Model Context Protocol (MCP) is an open standard for connecting AI to external tools and data. Add an MCP server to your workspace and its tools become available to your agents — a way to integrate services Sim doesn't have a built-in integration for.
Adding an MCP Server as a Tool
MCP servers provide collections of tools that your agents can use.
To add one:
- Navigate to Settings → MCP Tools
- Click Add to open the configuration modal
- Enter a Server Name and Server URL
- Add any required Headers (e.g. API keys)
- Click Add MCP to save
You can also configure MCP servers directly from the toolbar in an Agent block for quick setup.
Server Configuration Options
| Field | Description |
|---|---|
| Name | Display name for the server |
| URL | The MCP server endpoint |
| Transport | Currently supports streamable-http |
| Headers | Key-value pairs for authentication or custom headers |
| Timeout | Connection timeout in milliseconds (default: 30,000) |
Environment Variables in Configuration
Server URLs and headers support environment variable substitution using {{VAR_NAME}} syntax. This keeps sensitive values like API keys out of the server configuration.
URL: https://api.example.com/mcp
Authorization: Bearer {{MCP_API_TOKEN}}When you type {{ in the URL or header fields, a dropdown appears showing available workspace environment variables.
Testing and Validation
Click Test Connection before saving to verify the server is reachable and discover available tools. The test response shows the number of tools found and the protocol version.
After saving, each server displays its available tools with parameter names, types, and required flags. If a server's tools change (e.g., after a server update), click Refresh to fetch the latest schemas. This automatically updates any agent blocks using those tools.
Tool validation badges appear on servers with issues — for example, if a tool was removed from the server but is still referenced in a workflow. Click the badge to see which workflows are affected.
Domain Allowlisting
Self-hosted deployments can restrict which MCP server domains are allowed by setting the ALLOWED_MCP_DOMAINS environment variable (comma-separated list). When set, only servers on approved domains can be added. When unset, all domains are allowed.
Using MCP Tools in Agents
Once MCP servers are configured, their tools become available within your agent blocks:
- Open an Agent block
- In the Tools section, click Add tool…
- Under MCP Servers, click a server to see its tools
- Select individual tools, or choose Use all N tools to add every tool from that server
- The agent can now access these tools during execution
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.
Standalone MCP Tool Block
For more granular control, you can use the dedicated MCP Tool block to execute specific MCP tools:
The MCP Tool block runs one configured tool with parameters you set explicitly, and its output is readable by later blocks like any other.
When to Use MCP Tool vs Agent
| 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
MCP functionality requires specific workspace permissions:
| Action | Required Permission |
|---|---|
| Create or update MCP servers | Write or Admin |
| Delete MCP servers | Admin |
| Use MCP tools in agents | Write or Admin |
| View available MCP tools | Read, Write, or Admin |
| Execute MCP Tool blocks | Read, Write, or Admin |
MCP servers run with the permissions of the user who configured them — only connect servers you trust, and review a server's tools before handing them to agents.