Connect external MCP servers

Connect your Toolhouse agents to any external MCP (Model Context Protocol) server to extend functionality and integrate with third-party services.

Your agents can connect to external MCP servers. This is useful when you want to seamlessly connect your Toolhouse agents to services beyond our native tool collection. By connecting external MCP servers, you can:

• Connect to third-party APIs: Integrate with external services like Slack, Notion, GitHub, and more

• Choose your preferred providers: Select MCP servers that best fit your specific needs, and seamlessly switch between MCP providers without changing your code

• Access your internal data: Connect agents to your organization's internal APIs and services

• Build custom integrations: Extend Toolhouse functionality with your own custom tools and workflows

Connecting to an external MCP server

Connecting to an external MCP server is very simple:

1

Find a remote MCP server

You will need to find an MCP server you want your agents to connect to. Here are some servers you can get started with:

• Smithery

• Zapier

• Pipedream

Note: this is not a comprehensive list of servers. Uou can bring any remote server that supports the Streamable HTTP or SSE transports. If you own an MCP server that you deployed in the cloud, you can also use that.

2

Obtain your MCP Server URL

Once you choose a service, you will need to authenticate it and configure it. Follow the instructions, then copy the URL link you receive from the service you chose.

Smithery

1. Go to Smithery.

2. Search for the service you want to add to your agent. Ensure you select a service labeled as Remote.

3. Click Generate URL.

4. Fill in any required fields.

5. Copy the URL you receive.

6. Tell Agent Studio: "add this MCP server:" followed by the URL you copied.

Zapier

1. Go to Zapier.

2. Click New MCP Server.

3. Select Other.

4. Click Add Tool.

5. Select the tool or tools you want to add.

6. Complete any authentication steps, if asked.

7. Select the Connect tab.

8. Locate the Server URL field, then click Copy URL.

9. Tell Agent Studio: "add this MCP server:" followed by the URL you copied.

Pipedream

1. Go to Pipedream.

2. Search for the app you want to add.

3. Complete any authentication steps, if asked.

4. Locate the MCP Server URL field, then click the Copy button.

5. Tell Agent Studio: "add this MCP server:" followed by the URL you copied.

Configuration

Add external MCP servers to your agent by including an mcp_servers section in your .th file:

title: Your Agent Name

system_prompt: |-
  Your agent instructions here...

message: "Your initial message"

mcp_servers:
  - https://docs.mcp.cloudflare.com/sse
  - https://mcp.pipedream.net/d7ddb9a0-xxxx-xxxx-xxxx-892dde51c673/notion
  - https://server.smithery.ai/@smithery-ai/slack/mcp?api_key=your_api_key

Example: Cloudflare Documentation Agent

Here's a complete example that creates an agent to query Cloudflare documentation and send results via Slack:

title: Cloudflare Help

system_prompt: |-
  You are a brilliant AI assistant that specializes in using tools to retrieve information and perform tasks. You have access to the Cloudflare tool to look up answers to user questions, and you can send messages using the Slack tool.
  
  You MUST follow these instructions:
  1. Use the Cloudflare tool to look up the answer to the user's question.
  2. With the result, use the Slack tool to send a message to @daniele with the result.

  IMPORTANT: YOU MUST CALL THE SLACK TOOL AT LEAST ONCE.

message: "how do I set up a Cloudflare worker?"

mcp_servers:
  - "https://docs.mcp.cloudflare.com/sse"
  - "https://server.smithery.ai/@smithery-ai/slack/mcp?api_key=your_api_key&profile=your_profile_name&config=config_in_urlencoded_base64"

If the MCP server you chose doesn't work, check the following:

• Ensure the server supports either the Streamable HTTP or the legacy SSE transports.

• Ensure the you passed the correct link, complete with any authentication tokens or API keys.

Toolhouse automatically detects the appropriate transport for each MCP server. If the connection fails, your agent will likely not return any answer or display an error. In that case, verify that your server uses one of the supported transports, and that the server URL is correct.

Authentication details, such your unique token or API Key to the MCP server, must be provided in the URL itself.

Working with multiple MCP servers

You can connect to multiple MCP servers simultaneously, including servers from different providers. List each server URL on a separate line in the mcp_servers section.

When multiple MCP servers provide tools with identical names, only the tool from the last specified MCP server URL will be available to your agent.

If your agent is not calling an MCP server as expected, try this:

Clear system instructions. Explicitly describe the task by starting your system_prompt with this sentence:

You are a brilliant AI assistant that specializes in using tools to retrieve information and perform tasks.

Try a different models. Some models may perform better with external tool calling. You can use a more powerful model, such as a reasoning model, to improve the MCP server calling performance. We suggest using a more powerful model when the agent needs to sequence calls in a specific way.