Overview

MCP (Model Context Protocol) Connectors allow you to extend Assembled AI capabilities by connecting to external MCP servers. This enables your AI agents to access real-time data, perform actions, and integrate with third-party systems during customer conversations.

MCP is an open standard that allows AI assistants to connect to external data sources and tools through a unified protocol. By configuring MCP connectors in Assembled, you can:

• Access external data (query customer databases, CRMs, ticketing systems, and more)
• Perform actions (create tickets, update records, process refunds, trigger workflows)
• Extend AI capabilities (access specialized tools and knowledge bases)
• Integrate seamlessly (connect to any MCP-compatible service without custom development)

Access requirements

• The feature must be enabled for your workspace. Contact your AI Deployments Strategist to request access.
• To add, edit, or disconnect connectors and change tool types, you need the Edit API Endpoints permission. View-only users can see the page but cannot make changes.

Use cases

Customer Data Lookup: Retrieve account information, order history, subscriptions, customer status and eligibility, transaction and payment history.

Action Execution: Process refunds and cancellations, update customer records, create or modify support tickets, trigger automated workflows.

Knowledge Augmentation: Access product catalogs and pricing information, query internal wikis and documentation, retrieve policy and procedure information.

How this differs from the Assembled MCP Server

These two features are easy to confuse — they point in opposite directions:

This article covers MCP Connectors. For the Assembled MCP Server, see its dedicated article.

Requirements

Before setting up a connector, confirm your MCP server meets these requirements:

• HTTPS only. HTTP URLs are rejected.
• Publicly resolvable hostname. Localhost and private IP ranges (e.g., 10.x, 192.168.x) are blocked.
• Inbound access from Assembled. If your account uses Static IP + proxy or your infrastructure team operates an IP allowlist, work with Assembled to confirm the egress IPs that need to be allowlisted on your MCP server side.

If your MCP server is hosted on a private network, you'll need a public HTTPS endpoint that fronts it — Assembled cannot reach internal-only hostnames.

Set up a connector

Step 1: Navigate to MCP connectors

In Assembled:

• Go to Configure in the left sidebar
• Under AI Agent Setup, select Tools and connectors
• Click the MCP connectors tab

Step 2: Add a custom connector

Click Add custom connector. The connector configuration sheet will open.

Step 3: Configure connection details

Name: Enter a descriptive name for your connector (e.g., "Customer Database", "CRM Integration"). This name helps identify the connector when managing multiple integrations.

URL: Enter the full HTTPS URL of your MCP server (example: https://mcp.yourcompany.com/api). HTTPS is required, and private/internal IPs are blocked.

Transport Type: Choose the communication protocol your MCP server supports:

• HTTP (HTTP streaming): Standard HTTP with streaming support (recommended for most use cases)
• SSE (Server-sent events): Server-sent events protocol (useful for real-time updates)

Authentication Method: Select how your AI agents authenticate with the MCP server:

• None: No additional credentials are sent beyond the URL itself. Note: this does not allow connecting to internal/private networks — HTTPS and a public hostname are still required.
• Bearer Token: Provide a bearer token. The token is sent in the Authorization header.
• API Key: Provide an API key. The key is sent in the Authorization header as the raw value — it is not automatically prefixed with Bearer. If your MCP server expects Bearer <key>, include the Bearer prefix in the value you store.
• OAuth: OAuth 2.0 client credentials flow, ideal for third-party integrations (e.g., Canva, external services). Required fields: Client ID (OAuth application client ID), Client Secret (OAuth application secret, securely stored), OAuth URL (token endpoint to exchange credentials for access tokens). The system automatically handles token retrieval and caching, and access tokens are refreshed as needed.

Custom Headers (Optional): Add any additional HTTP headers required by your MCP server. Useful for custom authentication or routing requirements.

Step 4: Save and connect

Click Add connector (for a new connector) or Update connector (when editing an existing one). Assembled will validate the configuration:

• For OAuth connectors, credentials are tested against the OAuth token endpoint before saving. A failed save usually indicates a bad OAuth URL or credentials.
• If validation passes, the connector appears in the MCP connectors list and tools are automatically synced.
  
  

Server-supplied instructions

Some MCP servers return instructions during the initial sync that describe how their tools should be used. If your server provides these, Assembled displays them on the connector card. These instructions come directly from the MCP server and cannot be edited in the connector form.

Manage tools

Once a connector is successfully configured, Assembled automatically syncs all available tools from the MCP server.

Viewing synced tools

Go to Configure → Tools and connectors → Tools. This tab is a combined view of multiple tool types:

• MCP tools (grouped by connector)
• Custom APIs
• SQL query tools (when database connectors are enabled for your workspace)

Each MCP tool displays its name, title, description, and type (read-only or write-enabled).

Configuring Read-only vs Write tools

When new tools are synced, their Type is unset by default. Admins must mark each tool as Read-only or Write in the Tools table. This matters because:

• Read-only tools retrieve information without changing data
• Write tools modify data — and are skipped in dry-run mode

Tools with no type set may still execute in dry-run mode, so it's important to set the type explicitly for any tool that modifies data.

Editing a connector

Go to Configure → Tools and connectors → MCP connectors, open the connector's menu, select Edit, update any fields (URL, authentication, headers, etc.), and click Update connector.

Disconnecting a connector

To remove a connector, open the connector's menu and select Disconnect. The connector is removed immediately. Disconnecting a connector:

• Removes all synced tools
• Prevents AI agents from using those tools in conversations
• Does not delete any historical data or conversation logs

Managing tools from a connector

To manage tools, open the connector's menu and select Manage tools. This switches to the Tools tab.

Testing tool functionality

1. Click on the tool name in the Tools table
2. Fill in the required parameters based on the tool's input schema
3. Click Test tool to execute the tool call
4. Review the JSON response to verify functionality

Resyncing tools

Tools sync automatically when a connector is created or updated, and a background job re-syncs all connectors periodically. If you need an immediate refresh after server-side changes:

MCP connectors tab → connector menu (three dots) → Resync tools. Assembled fetches the latest tool definitions, and any tools removed from the server are deleted from Assembled on sync.

Use MCP tools in AI Workflows

MCP tools are used in AI Workflows, not in Knowledge Guides. Workflows let you build multi-step agent flows where each step can call connector tools.

Inserting a connector tool in a workflow step

1. Open the relevant AI Workflow and navigate to the Guide step where the tool should be used.
2. In the Response instructions field, type @ to open the mention picker.
3. Select the connector tool you want to reference. It appears in your instructions as ConnectorName:tool_name (Connector) and is inserted as a token reference behind the scenes.
4. Write the surrounding instructions that tell the agent when to call the tool, what parameters to use, and how to handle the response.

Important: The agent calls a tool only when its inserted token reference appears in the instructions. Free-text tool names — for example, just typing "use the get_customer_info tool" — are unreliable. Always use the @ mention picker so the proper token is embedded.

Tool names with special characters are sanitized for the model, which is another reason to use the picker rather than hand-typing names.

Example instruction shape

A workflow Guide step's Response instructions might read:

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 the customer_email parameter. If the tool returns an error, acknowledge the issue and suggest the customer contact billing@example.com.

(The @CustomerDB:get_customer_info portion is inserted via the @ mention picker, not typed manually.)

How tools run during a conversation

Customer message → workflow evaluation → tool invocation → response integration → AI response to customer.

Note: MCP tool results in live conversations are truncated to approximately 5,000 characters. For large payloads, design your tools to return summaries or page through results.

Troubleshooting

Connection issues

Problem: "Failed to connect to MCP server"

Possible causes include an incorrect URL, network issues, authentication failure, or the MCP server being unavailable. Confirm the URL uses HTTPS and resolves publicly.

Problem: "Connection timeout"

Check MCP server load and firewall rules. If your account uses Static IP + proxy, confirm those IPs are allowlisted server-side. If the issue persists, contact your MCP server administrator or reach out to Assembled Support.

Tool sync issues

Problem: "No tools found" after connecting

Possible causes include the MCP server not exposing tools, the tool list endpoint not responding, or insufficient authentication permissions. Use Resync tools and verify server configuration and permissions.

Problem: "Tools out of date"

Click Resync tools on the connector to fetch the latest tool definitions.

Tool execution issues

Problem: Tool calls fail during conversations

Test the tool manually using Test tool, validate parameters, verify credentials and permissions, and review MCP server logs for errors.

Problem: AI does not use the tool when expected

The most common cause is the tool not being referenced via the @ mention picker in the workflow Guide step. Confirm the inserted token (ConnectorName:tool_name (Connector)) appears in the Response instructions. Also verify the workflow step is actually being entered for that customer scenario.

Authentication issues

401 Unauthorized: Verify credentials, expiration, and authentication method. For API Key auth, confirm whether your server expects a raw key or Bearer <key> — the value is sent as-is.

403 Forbidden: Credentials are valid but lack required permissions; contact your MCP server administrator.

Best practices

Security

• Use HTTPS only: HTTP URLs are rejected.
• Rotate credentials regularly: Update bearer tokens and API keys periodically.
• Limit permissions: Grant only the minimum necessary permissions to API keys.
• Mark write tools explicitly: Set Tool Type to Write for anything that modifies data so dry-run mode skips it.
• Test in development first: Always test new connectors in a non-production environment.

Workflow instructions

• Use the @ mention picker: Always insert tool references via @ mention rather than typing tool names by hand.
• Be explicit: Clearly state when the agent should use each tool.
• Provide context: Explain what information the tool provides or what action it performs.
• Specify parameters: Indicate which customer information should be passed to the tool.
• Handle errors: Include instructions for what the agent should do if a tool call fails.

Performance

• Minimize tool calls: Only call tools when necessary.
• Optimize tool response time: Work with your MCP server team to ensure fast responses.
• Monitor tool usage: Regularly review which tools are being used and how often.
• Handle timeouts: Ensure your MCP server responds within acceptable timeframes.
• Watch for truncation: Live conversation tool results truncate around 5,000 characters — return summaries when possible.

FAQs

How do I get access? MCP Connectors are currently in alpha. Contact your AI Deployments Strategist to request access for your workspace.

Can I use multiple MCP connectors? Yes, multiple connectors can be configured and used simultaneously.

What happens if a tool call fails? The AI receives an error and responds based on workflow instructions.

Can I control which workflows use which tools? Yes — tools are scoped per workflow Guide step via the @ mention picker.

Are there rate limits on tool calls? Rate limits depend on your MCP server; Assembled does not impose additional limits.

Can customers see when tools are being used? No, tool usage is not visible to customers.

What's the difference between Read-only and Write tools? Read-only tools retrieve information; Write tools modify data. Write tools are skipped in dry-run mode — but only when explicitly marked as Write. Tools with no type set may still execute in dry run.

Do I need to be a developer to set this up? No, but you'll need: the Edit API Endpoints permission in Assembled, your MCP server details, and an understanding of the tools your MCP server exposes.