# Custom MCP servers integrations

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:

{% stepper %}
{% step %}

### 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](https://smithery.ai/)
* [Zapier](https://mcp.zapier.com/)
* [Pipedream](https://mcp.pipedream.com/)

**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.
{% endstep %}

{% step %}

### 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](https://smithery.ai/).
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](https://mcp.zapier.com/).
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](https://mcp.pipedream.com/).
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 <i class="fa-copy">:copy:</i> Copy button.
5. Tell Agent Studio: "add this MCP server:" followed by the URL you copied.
   {% endstep %}
   {% endstepper %}

### Configuration

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

```yaml
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
```

<details>

<summary>Example: Cloudflare Documentation Agent</summary>

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

```yaml
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"
```

</details>

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.

{% hint style="info" %}
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.
{% endhint %}

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:

{% code overflow="wrap" %}

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

{% endcode %}

**Try a different models.** Some models may perform better with external tool calling. You can [use a more powerful model](https://docs.toolhouse.ai/toolhouse/advanced-concepts/bring-your-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.