MCP connectors

Plans and permissions:

• Add-on: AI agents, billed separately
• Add, edit, or remove MCP connectors and set tool types: Admin role, or a custom role with Tools and connectors set to Can edit tools and connectors settings
• View connectors and tools: Admin role, or a custom role with Tools and connectors set to Can edit tools and connectors settings or Can view tools and connectors settings
• Use MCP tools in a workflow: Admin, Manager, or Team Lead role, or a custom role with Workflows set to Can create, edit, and delete workflows
• To turn on MCP connectors for your company, contact our team.

Use MCP connectors to give your AI agents tools from your own systems, such as looking up an account, checking an order, or processing a refund, during a conversation. MCP (Model Context Protocol) is an open standard for connecting AI assistants to external tools. You add the URL of an MCP server, Assembled syncs the tools it offers, and you choose where your workflows use them.

To add one, go to Configure > Tools and connectors and select Add connector > MCP connector.

How MCP connectors work

• You can use MCP tools to look up customer data, such as account details, orders, subscriptions, and payment history, and to take actions, such as processing refunds, updating records, or creating tickets. They can also reach product catalogs, internal wikis, and policies.
• When a connector is added or updated, Assembled syncs every tool the server offers. Assembled also re-syncs all connectors regularly.
• Some MCP servers send instructions on how to use their tools. Assembled shows them on the connector’s page, and you can’t edit them in Assembled.
• Workflows use the tools in two ways: as an MCP tool step, or as a reference in a Guide step. A tool is only used where you’ve added it.
• In a conversation, the AI agent calls the tool, gets the result, and uses it in its reply. Results longer than about 5,000 characters are cut off, so tools should return summaries or pages of results.
• If a tool call fails, the AI agent gets the error and responds as your workflow instructions say.
• You can add as many connectors as you need. Customers don’t see when a tool is used.
• Rate limits on tool calls depend on your MCP server. Assembled doesn’t add its own.

MCP connectors and the Assembled MCP Server

The two features work in opposite directions.

What your MCP server needs

• HTTPS. HTTP URLs are rejected.
• A public hostname. Localhost and private IP ranges, such as 10.x or 192.168.x, are blocked. If your MCP server is on a private network, put a public HTTPS endpoint in front of it.
• Access from Assembled. If your server only accepts traffic from known IP addresses, turn on static egress IPs and add those addresses to your allowlist. See Use static egress IPs.

Add an MCP connector

1. Go to Configure > Tools and connectors.
2. Select Add connector, then MCP connector.
3. Enter a Name that identifies the server, such as Customer database or CRM.
4. Enter the URL: the full HTTPS URL of your MCP server, such as https://mcp.yourcompany.com/api.
5. Choose the Transport type your server supports. See MCP connector options.
6. Choose an Authentication method and enter its details.
7. Optionally, under Custom headers, add any other headers your server needs, as a Key and Value.
8. Select Add connector.

Assembled checks the connection before saving. For OAuth, it also tests your credentials against the token endpoint. If you see “Failed to create connector, check your credentials or URL.”, check the URL, the credentials, and, for OAuth, the OAuth URL. When it works, the connector appears on the Tools and connectors page with its synced tools.

MCP connector options

Review a connector’s tools

On Configure > Tools and connectors, you can search the connectors, sort them, and select MCP to show only MCP connectors. Select a connector to open its page, which shows its Host URL, Transport, and Authentication, any instructions from the server, and its tools. Each tool shows its name, title, description, and type. To find a tool, use Search tools….

Set each tool’s type

When a tool is first synced, it has no type. Set one for every tool:

1. On the connector’s page, select the tool.
2. Under Tool type, choose Read-only for tools that only retrieve information, or Write for tools that change data.
3. Select Save changes.

Important: When you test a workflow, tools marked Write don’t run, so a test doesn’t change your data. A tool with no type set can still run during a test. Mark every tool that changes data as Write.

Test a tool

1. On the connector’s page, select the tool.
2. Select Test tool.
3. Fill in the tool’s parameters.
4. Select Test tool to run it.

You see Tool ran successfully or Tool run failed, with the JSON response. Testing runs the tool for real, so use test data for tools that change data.

Edit, re-sync, or remove a connector

Open the connector’s page and use the connector actions menu:

• Edit connector: change the URL, authentication, or headers, then select Update connector. Tools sync again when you save.
• Re-sync tools: fetch the latest tools from the server right away, for example after you’ve changed them on the server. Tools that are no longer on the server are removed from Assembled.
• Remove connector: removes the connector and all its tools at once. AI agents can no longer use them, but past conversations and their logs are kept.

Important: Workflow steps and Guide steps that use the connector’s tools can’t run after you remove it. Update those workflows first.

Use MCP tools in workflows

Add an MCP tool step

1. In the workflow builder, select + after a step, select Add step, and choose MCP tool.
2. Choose the MCP connector and the Tool.
3. Under Tool inputs, set each parameter from a Smart field or a Fixed value.
4. Optionally, change the Request timeout.
5. To handle errors separately, turn on Branch based on tool result, which gives the step a success branch and an error branch.
6. Under Output mapping, map each Response field to a Stored variable for later steps.
7. Select Update step.

If you don’t see MCP tool in the list of steps, contact our team to turn it on.

Use a tool in a Guide step

1. Open the workflow and select the Guide step.
2. In Response instructions, type @ and choose the connector tool. It appears in your instructions as the connector name and tool name.
3. Around it, write when to call the tool, what to pass to it, and what to do with the result or an error.
4. Select Save step.

Important: The AI agent calls a tool only when it’s inserted from the @ menu. A tool name typed as plain text isn’t reliable, especially for names with special characters.

For example: “When the customer asks about their account status, use @CustomerDB:get_customer_info to look up their account by email. Pass the customer’s email address as customer_email. If the tool returns an error, apologize and offer to hand the conversation to a team member.”

Use static egress IPs

If your MCP server or firewall only accepts known IP addresses, you can send connector traffic from a fixed set of Assembled addresses.

1. Go to Configure > Tools and connectors.
2. Open the page’s More actions menu and select Static egress IPs.
3. Turn on Use static egress IPs.
4. Add the addresses shown in the dialog to your server’s allowlist.

This setting applies to MCP connectors and Snowflake database connectors for your whole company.

Best practices

• Limit what credentials can do. Give tokens and API keys only the permissions the tools need, and rotate them regularly.
• Mark write tools. Set Tool type to Write for anything that changes data.
• Test outside production first. Try new connectors against a test environment when you can.
• Be explicit in instructions. Say when to use each tool, what it returns, which customer details to pass, and what to do if it fails.
• Call tools only when needed. Fewer calls mean faster replies.
• Keep responses fast and short. Work with your server’s team on response times, and return summaries rather than large payloads.
• Review usage. Check which tools are used, and how often, on each workflow’s Monitor tab under Top data tools.

Common issues

• The connector can’t connect: Check that the URL uses HTTPS and a public hostname, that the server is running, and that the credentials are right.
• The connection times out: Check the server’s load and firewall rules. If you use static egress IPs, check that they’re on the allowlist.
• No tools appear after connecting: Check that the server exposes tools and that the credentials can list them. Then select Re-sync tools.
• Tools are out of date: Select Re-sync tools.
• A tool fails in conversations: Run it with Test tool, check its parameters and credentials, and check your server’s logs.
• The AI agent doesn’t use the tool: Check that the tool is inserted from the @ menu in the Guide step, and that the workflow reaches that step for the case.
• A 401 Unauthorized error: Check the credentials, their expiry, and the authentication method. For API key, check whether your server expects the raw key or Bearer <key>.
• A 403 Forbidden error: The credentials work but don’t have the permissions the tool needs. Ask your MCP server’s administrator.