flow/docs/versioned_docs/version-1.9.0/Agents/mcp-client.mdx

---
title: Use Hanzo Flow as an MCP client
slug: /mcp-client
---

import Icon from "@site/src/components/icon";
import McpIcon from '@site/static/logos/mcp-icon.svg';
import PartialMcpNodeTip from '@site/docs/_partial-mcp-node-tip.mdx';
import PartialMcpToolsAddSteps from '@site/docs/_partial-mcp-tools-add-steps.mdx';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Hanzo Flow integrates with the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) as both an MCP server and an MCP client.

This page describes how to use Hanzo Flow as an MCP client with the [**MCP Tools** component](#use-the-mcp-tools-component) and connected [MCP servers](#manage-connected-mcp-servers).

For information about using Hanzo Flow as an MCP server, see [Use Hanzo Flow as an MCP server](/mcp-server).

## Use the MCP tools component {#use-the-mcp-tools-component}

The **MCP Tools** component connects to an MCP server so that a [Hanzo Flow agent](/agents) can use the server's tools when responding to user queries.

Register MCP servers, and then add **MCP Tools** from the <McpIcon /> **MCP** sidebar as described in [Connect to a non-Hanzo Flow MCP server](#mcp-stdio-mode).

This component has two modes, depending on the type of server you want to access:

* [Connect to a non-Hanzo Flow MCP server](#mcp-stdio-mode) with a JSON configuration file, server start command, or HTTP/SSE URL to access tools provided by external, non-Hanzo Flow MCP servers.
* [Connect to a Hanzo Flow MCP server](#mcp-http-mode) to use flows from your [Hanzo Flow projects](/concepts-flows#projects) as MCP tools.

### Connect to a non-Hanzo Flow MCP server {#mcp-stdio-mode}

<PartialMcpNodeTip />

<PartialMcpToolsAddSteps />

4. In the **MCP Server** field on the **MCP Tools** component, select the server you registered.

    New servers are registered in **Settings** > **MCP Servers**, or in the <McpIcon /> **MCP** sidebar > <Icon name="Plus" aria-hidden="true"/> **Add MCP Server**, using one of the following connection types:

    * **JSON**: Paste the MCP server's JSON configuration object into the field, including required and optional parameters that you want to use, and then click **Add Server**.
    * **STDIO**: Enter the MCP server's **Name**, **Command**, and any **Arguments** and **Environment Variables** the server uses, and then click **Add Server**.
    For example, to start a [Fetch](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) server, the **Command** is `uvx mcp-server-fetch`.
    * **HTTP/SSE**: Enter your MCP server's **Name**, **URL**, and any **Headers** and **Environment Variables** the server uses, and then click **Add Server**.
    The default **URL** for Hanzo Flow MCP servers is `http://localhost:7860/v1/mcp/project/PROJECT_ID/streamable` or `http://localhost:7860/v1/mcp/streamable`. For more information, see [Connect to a Hanzo Flow MCP server](#mcp-http-mode).

5. To configure headers for your MCP server, enter each header in the **Headers** fields as key-value pairs.
    You can use [global variables](/configuration-global-variables) in header values by entering the global variable name as the header value.
    For more information, see [Use global variables in MCP server headers](#use-global-variables-in-mcp-server-headers).

6. To use environment variables in your server command, enter each variable in the **Env** fields as key-value pairs.

7. In the **Tool** field, select a tool that you want this component to use, or leave the field blank to allow access to all tools provided by the MCP server.

    If you select a specific tool, you might need to configure additional tool-specific fields. For information about tool-specific fields, see your MCP server's documentation.

    At this point, the **MCP Tools** component is serving a tool from the connected server, but nothing is using the tool. The next steps explain how to make the tool available to an [**Agent** component](/components-agents) so that the agent can use the tool in its responses.

8. In the [component's header menu](/concepts-components#component-menus), enable **Tool mode** so you can use the component with an agent.

9. Connect the **MCP Tools** component's **Toolset** port to an **Agent** component's **Tools** port.

    If not already present in your flow, make sure you also attach **Chat Input** and **Chat Output** components to the **Agent** component.

    ![MCP Tools component in STDIO mode](/img/component-mcp-stdio.png)

10. Test your flow to make sure the MCP server is connected and the selected tool is used by the agent. Open the **Playground**, and then enter a prompt that uses the tool you connected through the **MCP Tools** component.

    For example, if you use `mcp-server-fetch` with the `fetch` tool, you could ask the agent to summarize recent tech news. The agent calls the MCP server function `fetch`, and then returns the response.

11. If you want the agent to be able to use more tools, repeat these steps to add more tools components with different servers or tools.

### Connect a Hanzo Flow MCP server {#mcp-http-mode}

Every Hanzo Flow project runs a separate MCP server that exposes the project's flows as MCP tools.
For more information about your projects' MCP servers, including exposing flows as MCP tools, see [Use Hanzo Flow as an MCP server](/mcp-server).

Hanzo Flow MCP servers support both the **streamable HTTP** transport and **Server-Sent Events (SSE)** as a fallback.

To leverage flows-as-tools, register your Hanzo Flow MCP endpoint as a server first, and then add the **MCP Tools** component from the <McpIcon /> **MCP** sidebar.

1. Register the Hanzo Flow MCP server.
 Open **Settings** > **MCP Servers** or the <McpIcon /> **MCP** section in the flow sidebar, click <Icon name="Plus" aria-hidden="true"/> **Add MCP Server**, and select **HTTP/SSE** mode.

2. In the **MCP URL** field, enter your Hanzo Flow server's MCP endpoint.
   - For project-specific servers: `http://localhost:7860/v1/mcp/project/PROJECT_ID/streamable`
   - For global MCP server: `http://localhost:7860/v1/mcp/streamable`
   - Default for Hanzo Flow Desktop: `http://localhost:7868/`

   All flows available from the targeted server are treated as tools. For authentication and project URLs, see [Use Hanzo Flow as an MCP server](/mcp-server).

3. Save the server. When the connection succeeds, the server is stored and appears as a tile in the **MCP** sidebar.

4. Add the **MCP Tools** component to the flow.

5. In the [component's header menu](/concepts-components#component-menus), enable **Tool Mode** so you can use the component with an agent.

6. Connect the **MCP Tools** component's **Toolset** port to an **Agent** component's **Tools** port.

7. If not already present in your flow, make sure you also attach **Chat Input** and **Chat Output** components to the **Agent** component.

    ![MCP component with HTTP/SSE mode enabled](/img/component-mcp-sse-mode.png)

8. Test your flow to make sure the agent uses your flows to respond to queries. Open the **Playground**, and then enter a prompt that uses a flow that you connected through the **MCP Tools** component.

9. If you want the agent to be able to use more tools, repeat these steps to add more tools components with different servers or tools.

## MCP Tools parameters

| Name | Type | Description |
|------|------|-------------|
| mcp_server | String | Input parameter. The MCP server to connect to. |
| tool | String | Input parameter. The specific tool to execute from the connected MCP server. Leave blank to allow access to all tools. |
| use_cache | Boolean | Input parameter. Enable caching of MCP server and tools to improve performance. Default: `false`. |
| verify_ssl | Boolean | Input parameter. Enable SSL certificate verification for HTTPS connections. Default: `true`. |
| response | Table | Output parameter. [`Table`](/data-types#table) containing the response from the executed tool. |

## Manage connected MCP servers

To manage MCP server connections for use in flows, open the <McpIcon /> **MCP** section in the visual editor, and then click <Icon name="ArrowUpRight" aria-hidden="true"/> **Manage Servers**, or click your profile icon, select **Settings**, and then click **MCP Servers**.

To add a new MCP server, click <Icon name="Plus" aria-hidden="true"/> **Add MCP Server**, register the server, and then select the server on the **MCP Tools** component as described in [Connect to a non-Hanzo Flow MCP server](#mcp-stdio-mode).

Click <Icon name="Ellipsis" aria-hidden="true"/> **More** to edit or delete an MCP server connection.

## Modify MCP server environment variables with the API {#mcp-api-tweaks}

You can modify MCP server environment variables at runtime when running flows through the [Hanzo Flow API](/api-reference-api-examples) by tweaking the **MCP Tools** component.

You can include tweaks with any Hanzo Flow API request that supports the `tweaks` parameter, such as POST requests to the `/run` or `/webhook` endpoints.
For more information, see [Input schema (tweaks)](/concepts-publish#input-schema).

To modify the **MCP Tools** component's environment variables with tweaks, do the following:

1. Open the flow that contains your **MCP Tools** component.
2. To find the **MCP Tools** component's unique ID, in your **MCP Tools** component, click <Icon name="SlidersHorizontal" aria-hidden="true"/> **Controls**.
The component's ID is displayed in the **Controls** pane, such as `MCPTools-Bzahc`.
3. Send a POST request to the Hanzo Flow server's `/run` endpoint, and include tweaks to the **MCP Tools** component.

    The following examples demonstrate a request structure with the `env` object nested under `mcp_server` in the `tweaks` payload:

    <Tabs groupId="language">
    <TabItem value="python" label="Python" default>

    ```python
    import requests
    import os

    FLOW_SERVER_ADDRESS = "http://localhost:7860"
    FLOW_ID = "your-flow-id"
    FLOW_API_KEY = os.getenv("FLOW_API_KEY")
    MCP_TOOLS_COMPONENT_ID = "MCPTools-Bzahc"

    url = f"{FLOW_SERVER_ADDRESS}/v1/run/{FLOW_ID}?stream=false"
    headers = {
        "Content-Type": "application/json",
        "x-api-key": FLOW_API_KEY
    }
    payload = {
        "output_type": "chat",
        "input_type": "chat",
        "input_value": "What sales data is available to me?",
        "tweaks": {
            MCP_TOOLS_COMPONENT_ID: {
                "mcp_server": {
                    "env": {
                        "API_URL": "https://api.example.com",
                        "API_KEY": "your-mcp-server-api-key",
                        "ENVIRONMENT": "production"
                    }
                }
            }
        }
    }

    response = requests.post(url, json=payload, headers=headers)
    print(response.json())
    ```

    </TabItem>
    <TabItem value="typescript" label="TypeScript">

    ```typescript
    const FLOW_SERVER_ADDRESS = "http://localhost:7860";
    const FLOW_ID = "your-flow-id";
    const FLOW_API_KEY = process.env.FLOW_API_KEY || "";
    const MCP_TOOLS_COMPONENT_ID = "MCPTools-Bzahc";

    const url = `${FLOW_SERVER_ADDRESS}/v1/run/${FLOW_ID}?stream=false`;

    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": FLOW_API_KEY,
      },
      body: JSON.stringify({
        output_type: "chat",
        input_type: "chat",
        input_value: "What sales data is available to me?",
        tweaks: {
          [MCP_TOOLS_COMPONENT_ID]: {
            mcp_server: {
              env: {
                API_URL: "https://api.example.com",
                API_KEY: "your-mcp-server-api-key",
                ENVIRONMENT: "production",
              },
            },
          },
        },
      }),
    });

    const data = await response.json();
    console.log(data);
    ```

    </TabItem>
    <TabItem value="curl" label="cURL">

    ```bash
    curl --request POST \
      --url "http://FLOW_SERVER_ADDRESS/v1/run/FLOW_ID?stream=false" \
      --header "Content-Type: application/json" \
      --header "x-api-key: FLOW_API_KEY" \
      --data '{
        "output_type": "chat",
        "input_type": "chat",
        "input_value": "What sales data is available to me?",
        "tweaks": {
          "MCP_TOOLS_COMPONENT_ID": {
            "mcp_server": {
              "env": {
                "API_URL": "https://api.example.com",
                "API_KEY": "your-mcp-server-api-key",
                "ENVIRONMENT": "production"
              }
            }
          }
        }
      }'
    ```

    </TabItem>
    </Tabs>

    Replace `MCP_TOOLS_COMPONENT_ID`, `FLOW_API_KEY`, `FLOW_SERVER_ADDRESS`, and `FLOW_ID` with the actual values from your Hanzo Flow deployment.

    Hanzo Flow doesn't automatically discover or expose which environment variables your MCP server accepts from the **MCP Tools** component.
    To determine which environment variables your MCP server accepts, see the MCP server's documentation. For example, the [Astra DB MCP server](https://github.com/datastax/astra-db-mcp) requires `ASTRA_DB_APPLICATION_TOKEN` and `ASTRA_DB_API_ENDPOINT`, with an optional variable for `ASTRA_DB_KEYSPACE`, as documented in its repository.

## Use global variables in MCP server headers {#use-global-variables-in-mcp-server-headers}

You can use [global variables](/configuration-global-variables) in MCP server header values to securely store and reference API keys, authentication tokens, and other sensitive values. This is particularly useful for deployment scenarios where you need to pass user-specific credentials at runtime.

Enter a global variable name as the header value, and Hanzo Flow resolves the global variable name to its actual value before making the MCP server request. Hanzo Flow only passes the token value to your server; it doesn't validate tokens on behalf of your MCP server.

For example, to create a global variable named `TEST_BEARER_TOKEN` for MCP server bearer authentication, do the following:

1. To open the **Global Variables** pane, click your profile icon, select **Settings**, and then click <Icon name="Globe" aria-hidden="true"/> **Global Variables**.
2. Create a **Credential** global variable named `TEST_BEARER_TOKEN`.
3. In the **Value** field, enter your MCP server's bearer token value. The value must include the `Bearer` prefix with a space, for example: `Bearer eyJhbG...`.
4. Click **Save Variable**.
5. To manage MCP server connections for your Hanzo Flow client, click <McpIcon /> **MCP servers**, and then click <Icon name="ArrowUpRight" aria-hidden="true"/> **Manage Servers**, or click your profile icon, select **Settings**, and then click **MCP Servers**.
6. Click <Icon name="Plus" aria-hidden="true"/> **Add MCP Server**.
7. Select the following:
    * **Name**: test-mcp-server
    * **Streamable HTTP/SSE URL**: Your MCP server's URL, such as `http://127.0.0.1:8000/mcp`.
    * **Headers**: In the key field, enter the literal string `Authorization`. For the key's value, enter `TEST_BEARER_TOKEN`, or the exact name of your global variable.
8. Click **Create Server**.

   If the connection succeeds, Hanzo Flow shows the number of tools exposed by the server.

   After creating the server and global variable, you can connect to the server with the **MCP Tools** component, as explained in the next steps.

9. Add the **MCP Tools** component to a flow.
10. In the **MCP Tools** component, confirm the **MCP Server** is set to the server you created.
The MCP server configuration already includes the headers you configured earlier, so no further configuration is needed in the component. The global variable `TEST_BEARER_TOKEN` is automatically resolved when the component makes requests to the MCP server.

11. Optional: To override headers or add additional headers to the **MCP Tools** component, click the component to view the **Headers** parameter in the [component inspection panel](/concepts-components#component-menus), and then add header key values. Headers configured in the component take precedence over the headers configured in the MCP server settings.

12. Test your flow to make sure the agent uses your server to respond to queries. Open the **Playground**, and then enter a prompt that uses a tool that you connected through the **MCP Tools** component.

    Hanzo Flow automatically resolves `TEST_BEARER_TOKEN` to its actual value before sending the request to the MCP server. When your MCP server receives the request, the `Authorization` header contains the resolved token value.

## See also

- [Hanzo Flow MCP Client](./flow-mcp-client.mdx)
- [Use Hanzo Flow as an MCP server](/mcp-server)
- [Use a DataStax Astra DB MCP server with the MCP Tools component](/mcp-component-astra)