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

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

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Icon from "@site/src/components/icon";

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 server that exposes your flows as [tools](https://modelcontextprotocol.io/docs/concepts/tools) that [MCP clients](https://modelcontextprotocol.io/clients) can use when generating responses.

Hanzo Flow MCP servers support both the **streamable HTTP** transport and **Server-Sent Events (SSE)** as a fallback.
The default project MCP server configuration uses streamable HTTP transport at the URL path `/streamable`.

For information about using Hanzo Flow as an MCP client and managing MCP server connections within flows, see [Use Hanzo Flow as an MCP client](/mcp-client).

## Prerequisites

* A [Hanzo Flow project](/concepts-flows#projects) with at least one flow that has a [**Chat Output** component](/chat-input-and-output).

    The **Chat Output** component is required to use a flow as an MCP tool.

* Any LTS version of [Node.js](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) installed on your computer if you want to use MCP Inspector to [test and debug flows](#test-and-debug-flows).

* [ngrok installed](https://ngrok.com/docs/getting-started/#1-install-ngrok) and an [ngrok authtoken](https://dashboard.ngrok.com/get-started/your-authtoken) if you want to [deploy a public Hanzo Flow server](/deployment-public-server).

## Serve flows as MCP tools {#select-flows-to-serve}

When you create a [Hanzo Flow project](/concepts-flows#projects), Hanzo Flow automatically adds the project to your MCP server's configuration and makes the project's flows available as MCP tools.

If your Hanzo Flow server has authentication enabled (`AUTO_LOGIN=false`), the project's MCP server is automatically configured with API key authentication, and a new API key is generated specifically for accessing the new project's flows.
For more information, see [MCP server authentication](#authentication).


### Prevent automatic MCP server configuration for Hanzo Flow projects

To disable automatic MCP server configuration for new projects, set the `FLOW_ADD_PROJECTS_TO_MCP_SERVERS` environment variable to `false`.
For more information, see [MCP server environment variables](#mcp-server-environment-variables).

### Selectively enable and disable MCP servers for Hanzo Flow projects

With or without automatic MCP server configuration enabled, you can selectively enable and disable the projects that are exposed as MCP tools:

1. Click the **MCP Server** tab on the [**Projects** page](/concepts-flows#projects), or, when editing a flow, click **Share**, and then select **MCP Server**.

    ![MCP server projects page](/img/mcp-server.png)

    The **Flows/Tools** section lists the flows that are currently being served as tools on this MCP server.

2. To toggle exposed flows, click <Icon name="Wrench" aria-hidden="true"/> **Edit Tools**, and then select the flows that you want exposed as tools.
To prevent a flow from being used as a tool, clear the checkbox in the first column.

3. Close the **MCP Server Tools** dialog to save your changes.

    ![MCP Server Tools](/img/mcp-server-tools.png)

### Edit flow tool names and descriptions

Tool names and descriptions help MCP clients determine which actions your flows provide and when to use those actions.
It is recommended to provide clear, descriptive names and descriptions for all tools that you serve to MCP clients.

To edit the names and descriptions of flow tools on a Hanzo Flow MCP server, do the following:

1. Click the **MCP Server** tab on the [**Projects** page](/concepts-flows#projects), or, when editing a flow, click **Share**, and then select **MCP Server**.

2. Click <Icon name="Wrench" aria-hidden="true"/> **Edit Tools**.

3. Click the **Description** or **Tool** that you want to edit:

    - **Tool name**: Enter a name that makes it clear what the flow does when used as a tool by an agent.

    - **Tool description**: Enter a description that completely and accurately describes the specific actions the flow performs.

4. Close the **MCP Server Tools** dialog to save your changes.

#### Importance of tool names and descriptions

MCP clients use tool names and descriptions to determine which actions to use when generating responses.

Because MCP clients treat your Hanzo Flow project as a single MCP server with all of your enabled flows listed as tools, unclear names and descriptions can cause the agent to select tools incorrectly or inconsistently.

For example, a flow's default tool name is the flow ID, such as `adbbf8c7-0a34-493b-90ea-5e8b42f78b66`.
This provides no information to an agent about the type of flow or its purpose.

To provide more context about your flows, make sure to name and describe your flows clearly when configuring your Hanzo Flow project's MCP server.

Think of these names and descriptions as function names and code comments.
Use clear statements to describe the problems your flows solve.

<details>
<summary>Example: Tool name and description usage</summary>

For example, assume you create a flow based on the **Document Q&A** template that uses an LLM to chat about resumes, and then you give the flow the following name and description:

- **Tool name**: `document_qa_for_resume`

- **Tool description**: `A flow for analyzing Emily's resume.`

After connecting your Hanzo Flow MCP server to Cursor, you can ask Cursor about the resume, such as `What job experience does Emily have?`.
Using the context provided by your tool name and description, the agent can decide to use the `document_qa_for_resume` MCP tool to create a response about Emily's resume.
If necessary, the agent asks permission to use the flow tool before generating the response.

If you ask about a different resume, such as `What job experience does Alex have?`, the agent can decide that `document_qa_for_resume` isn't relevant to this request, because the tool description specifies that the flow is for Emily's resume.
In this case, the agent might use another available tool, or it can inform you that it doesn't have access to information about Alex's.
For example:

```
I notice you're asking about Alex's job experience.
Based on the available tools, I can see there is a Document QA for Resume flow that's designed for analyzing resumes.
However, the description mentions it's for "Emily's resume" not Alex's. I don't have access to Alex's resume or job experience information.
```

</details>

{/* The anchor on this section (connect-clients-to-use-the-servers-actions) is currently a link target in the Hanzo Flow UI. Do not change. */}
## Connect clients to your Hanzo Flow MCP server {#connect-clients-to-use-the-servers-actions}

Hanzo Flow provides automatic installation and code snippets to help you deploy your Hanzo Flow MCP servers to your local MCP clients.

<Tabs>
<TabItem value="JSON" label="JSON" default>

The JSON option allows you to connect a Hanzo Flow MCP server to any local or remote MCP client.
You can modify this process for any [MCP-compatible client](https://modelcontextprotocol.io/clients).

1. Install any [MCP-compatible client](https://modelcontextprotocol.io/clients).

    These steps use Cursor as an example, but the process is generally the same for all clients, with slight differences in client-specific details like file names.

2. In your client, add a new MCP server using the client's UI or configuration file.

    For example, in Cursor, go to **Cursor Settings**, select **MCP**, and then click **Add New Global MCP Server** to open Cursor's global `mcp.json` configuration file.

3. Recommended: Configure [authentication](#authentication) for your MCP server.

4. In Hanzo Flow, on the **Projects** page, click the **MCP Server** tab.

5. Click the **JSON** tab, copy the code snippet for your operating system, and then paste it into your client's MCP configuration file.
For example:

    ```json
    {
      "mcpServers": {
        "PROJECT_NAME": {
          "command": "uvx",
          "args": [
            "mcp-proxy",
            "--transport",
            "streamablehttp",
            "http://FLOW_SERVER_ADDRESS/v1/mcp/project/PROJECT_ID/streamable"
          ]
        }
      }
    }
    ```

    The **MCP Server** tab automatically populates the `FLOW_SERVER_ADDRESS` and `PROJECT_ID` values.

    The default Hanzo Flow server address is `http://localhost:7860`.
    If you are using a [public Hanzo Flow server](/deployment-public-server), the server address is automatically included.

    If your Hanzo Flow server requires authentication, you must include your Hanzo Flow API key or OAuth settings in the configuration.
    For more information, see [MCP server authentication](#authentication).

6. To include other environment variables with your MCP server command, add an `env` object with key-value pairs of environment variables. For example:

    ```json
    {
      "mcpServers": {
        "PROJECT_NAME": {
          "command": "uvx",
          "args": [
            "mcp-proxy",
            "--transport",
            "streamablehttp",
            "http://FLOW_SERVER_ADDRESS/v1/mcp/project/PROJECT_ID/streamable"
          ],
          "env": {
            "KEY": "VALUE"
          }
        }
      }
    }
    ```

    Don't add API keys in the `env` object, as these variables are specifically for the `mcp-proxy` process.
    Instead, add API keys under `args`.
    For an example, see [MCP server authentication](#authentication).

7. Save and close your client's MCP configuration file.

8. Confirm that your Hanzo Flow MCP server is on the client's list of MCP servers.
If necessary, restart your client to apply the modified configuration file.

</TabItem>
<TabItem value="auto" label="Auto install">

:::info
The auto install option is available only for specific MCP clients.
Auto install requires the client to be installed locally so Hanzo Flow can write to the client's configuration file.
If your client isn't supported, is installed remotely, or you need to pass additional environment variables, use the **JSON** option.
:::

1. Install [Cursor](https://docs.cursor.com/get-started/installation), [Claude](https://claude.ai/download), or [Windsurf](https://windsurf.com/download/editor) on the same computer where your Hanzo Flow server is running.

2. Recommended: Configure [authentication](#authentication) for your MCP server.

3. In Hanzo Flow, on the **Projects** page, click the **MCP Server** tab.

4. On the **Auto install** tab, find your MCP client provider, and then click <Icon name="Plus" aria-hidden="true"/> **Add**.

    Your Hanzo Flow project's MCP server is automatically added to the configuration file for your local Cursor, Claude, or Windsurf client.
    For example, with Cursor, the server configuration is added to the `mcp.json` configuration file.

    Hanzo Flow attempts to add this configuration even if the selected client isn't installed.
    To verify the installation, check the available MCP servers in your client.

</TabItem>
</Tabs>

Once your MCP client is connected to your Hanzo Flow project's MCP server, your flows are registered as tools.
Cursor determines when to use tools based on your queries, and requests permissions when necessary.
For more information, see the MCP documentation for your client, such as [Cursor's MCP documentation](https://docs.cursor.com/context/model-context-protocol).

## MCP server authentication {#authentication}

Each [Hanzo Flow project](/concepts-flows#projects) has its own MCP server with its own MCP server authentication settings.

When you create a new project, Hanzo Flow automatically configures authentication for the project's MCP server based on your Hanzo Flow server's authentication settings. If authentication is enabled (`AUTO_LOGIN=false`), the project is automatically configured with API key authentication, and a new API key is generated for accessing the project's flows.

To configure authentication for a Hanzo Flow MCP server, go to the **Projects** page in Hanzo Flow, click the **MCP Server** tab, click <Icon name="Fingerprint" aria-hidden="true"/> **Edit Auth**, and then select your preferred authentication method:

<Tabs groupId="auth-type">
<TabItem value="API key" label="API key">

When authenticating your MCP server with a Hanzo Flow API key, your project's MCP server **JSON** code snippets and **Auto install** configuration automatically include the `--headers` and `x-api-key` arguments in the **args** array (for streamable transport).

Click <Icon name="key" aria-hidden="true"/> **Generate API key** to automatically insert a new Hanzo Flow API key into the code template.
Alternatively, you can replace `YOUR_API_KEY` with an existing Hanzo Flow API key.

To add your API key to the configuration, use three separate entries in `args`: `"--headers"`, `"x-api-key"`, and your key value. For example:

```json
{
  "mcpServers": {
    "PROJECT_NAME": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "--transport",
        "streamablehttp",
        "--headers",
        "x-api-key",
        "YOUR_API_KEY",
        "http://FLOW_SERVER_ADDRESS/v1/mcp/project/PROJECT_ID/streamable"
      ]
    }
  }
}
```

</TabItem>
<TabItem value="OAuth" label="OAuth">

When OAuth is enabled, Hanzo Flow automatically starts an [MCP Composer](https://pypi.org/project/mcp-composer) instance for your project, creating a secure client-side proxy between MCP clients and the `mcp-proxy` on your server.

OAuth integration allows your Hanzo Flow MCP server to authenticate users and applications through any OAuth 2.0 compliant service. When users or applications connect to your MCP server, they are redirected to your chosen OAuth provider to authenticate. Upon successful authentication, they are granted access to your flows as MCP tools.

Before configuring OAuth in Hanzo Flow, you must first set up an OAuth application with an external OAuth 2.0 service provider.
You must register your Hanzo Flow server as an OAuth client, and then obtain the required values to complete the configuration in Hanzo Flow.

The following table describes the required values.
[GitHub OAuth](https://github.com/settings/developers) is used for example purposes.
Be sure to use the actual values from your own deployment.
For more information, see your OAuth provider's documentation.

| Field | Description | Source | Example |
|-------|-------------|--------|---------|
| **Host** | OAuth server host | MCP Composer default. | `localhost` |
| **Port** | OAuth server port | MCP Composer default. | `9000` |
| **Server URL** | Full OAuth server URL | Combines the MCP Composer default OAuth host and port. | `http://localhost:9000` |
| **Callback URL** | OAuth callback URL on your server | You define this full URL during OAuth app registration. This must match exactly what you register with your OAuth provider. | `http://localhost:9000/auth/idaas/callback` |
| **Client ID** | Your OAuth client identifier | From your OAuth provider. | `Ov23li9vx2grVL61qjb` |
| **Client Secret** | Your OAuth client secret | From your OAuth provider. | `1234567890abcdef1234567890abcdef12345678` |
| **Authorization URL** | OAuth authorization endpoint | From your OAuth provider. | `https://github.com/login/oauth/authorize` |
| **Token URL** | OAuth token endpoint for getting refresh tokens | From your OAuth provider. | `https://github.com/login/oauth/access_token` |
| **MCP Scope** | Scope for MCP operations | You define this. As of Hanzo Flow 1.6, `user` is the only available value. | `user` |
| **Provider Scope** | OAuth provider scope | You define this. As of Hanzo Flow 1.6, `openid` is the only available value. | `openid` |

To configure OAuth authentication:

1. Select **OAuth** as the authentication type.
2. Configure the OAuth settings with the values from your OAuth deployment.
    All values are required.

    The OAuth credentials are encrypted and stored securely in your Hanzo Flow database.

3. Click **Save**.

    Your MCP server's **JSON** code snippets and **Auto install** configuration are automatically updated with OAuth values. These are automatically used for new installations after enabling OAuth. However, you must manually update any existing installations, as explained in the next step.

4. If you already installed your Hanzo Flow MCP server in your MCP client, you must update your MCP client configuration to use the new OAuth settings after enabling OAuth on your MCP server.
The client update method depends on how you installed the server on the client:

    - **Auto install**: Manually update your client's config file using the updated JSON snippet from the **JSON** tab, or repeat the steps in [Auto-install](#connect-clients-to-use-the-servers-actions) to re-install the client with the updated settings.
    - **JSON option**: Copy the updated JSON snippet from the **JSON** tab and replace your existing configuration.
    - **New connections**: Use either the **Auto install** or **JSON** option. The OAuth settings are included automatically.

After you enable OAuth and update your client configuration, an OAuth callback window opens each time your MCP client attempts to authenticate with the server.
A successful authentication returns `Authentication complete. You may close this window.`
If your client doesn't open the OAuth window, try restarting the client to retrieve the updated configuration.

</TabItem>
<TabItem value="None" label="None">

When no authentication is configured, your MCP server becomes a public endpoint that anyone can access without providing credentials.
Only use this option when Hanzo Flow is running in a trusted environment.

</TabItem>
</Tabs>

## MCP server environment variables

The following environment variables set behaviors related to your Hanzo Flow projects' MCP servers:

| Variable | Format | Default | Description |
|----------|--------|---------|-------------|
| `FLOW_MCP_SERVER_ENABLED` | Boolean | `True` | Whether to initialize an MCP server for each of your Hanzo Flow projects. If `false`, Hanzo Flow doesn't initialize MCP servers. |
| `FLOW_MCP_SERVER_ENABLE_PROGRESS_NOTIFICATIONS` | Boolean | `False` | If `true`, Hanzo Flow MCP servers send progress notifications. |
| `FLOW_MCP_SERVER_TIMEOUT` | Integer | `20` | The number of seconds to wait before an MCP server operation expires due to poor connectivity or long-running requests. |
| `FLOW_MCP_MAX_SESSIONS_PER_SERVER` | Integer | `10` | Maximum number of MCP sessions to keep per unique server. |
| `FLOW_ADD_PROJECTS_TO_MCP_SERVERS` | Boolean | `True` | Whether to automatically add newly created projects to the user's MCP servers configuration. If `false`, projects must be manually added to MCP servers. |

{/* The anchor on this section (deploy-your-server-externally) is currently a link target in the Hanzo Flow UI. Do not change. */}
### Deploy your Hanzo Flow MCP server externally {#deploy-your-server-externally}

To deploy your Hanzo Flow MCP server externally, see [Deploy a public Hanzo Flow server](/deployment-public-server).

## Use MCP Inspector to test and debug flows {#test-and-debug-flows}

:::info Node prerequisite
MCP Inspector requires any LTS version of [Node.js](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) installed on your computer.
:::
[MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) is a common tool for testing and debugging MCP servers.
You can use MCP Inspector to monitor your flows and get insights into how they are being consumed by the MCP server.

1. Install MCP Inspector:

    ```bash
    npx @modelcontextprotocol/inspector
    ```

    For more information about configuring MCP Inspector, including specifying a proxy port, see the [MCP Inspector GitHub project](https://github.com/modelcontextprotocol/inspector).

2. Open a web browser and navigate to the MCP Inspector UI.
The default address is `http://localhost:6274`.

3. In the MCP Inspector UI, enter the connection details for your Hanzo Flow project's MCP server.
    The field values depend on your server's method of [authentication](#authentication).
    <Tabs groupId="auth-type">
      <TabItem value="API key" label="API key" default>

        - **Transport Type**: Select **STDIO**.
        - **Command**: `uvx`
        - **Arguments**: Enter the following list of arguments, separated by spaces. Replace the values for `YOUR_API_KEY`, `FLOW_SERVER_ADDRESS`, and `PROJECT_ID` with the values from your Hanzo Flow MCP server. For example:
            ```bash
            mcp-proxy --headers x-api-key YOUR_API_KEY http://FLOW_SERVER_ADDRESS/v1/mcp/project/PROJECT_ID/streamable
            ```

      </TabItem>
      <TabItem value="OAuth" label="OAuth">

        - **Transport Type**: Select **STDIO**.
        - **Command**: `uvx`
        - **Arguments**: Enter the following list of arguments, separated by spaces. Replace the value for `OAUTH_SERVER_URL` with the URL of your OAuth server. For example:
            ```bash
            mcp-composer --mode stdio --sse-url http://localhost:9000/sse --disable-composer-tools --client_auth_type oauth
            ```

      </TabItem>
      <TabItem value="None" label="None">

        - **Transport Type**: Select **SSE**.
        - **URL**: Enter the Hanzo Flow MCP server's endpoint. For example:
            ```bash
            http://localhost:7860/v1/mcp/project/d359cbd4-6fa2-4002-9d53-fa05c645319c/streamable
            ```

      </TabItem>
    </Tabs>

4. Click **Connect**.

    If the connection was successful, you should see your project's flows in the **Tools** tab.
    From this tab, you can monitor how your flows are being registered as tools by MCP, as well as test the tools with custom input values.

5. To quit MCP Inspector, press <kbd>Control+C</kbd> in the same terminal window where you started it.

## Troubleshoot Hanzo Flow MCP servers {#troubleshooting-mcp-server}

For troubleshooting advice for MCP servers and clients, see [Troubleshoot Hanzo Flow: MCP issues](/troubleshoot#mcp).

## See also

* [Use Hanzo Flow as an MCP client](/mcp-client)
* [Use a DataStax Astra DB MCP server](/mcp-component-astra)
* [MCP server environment variables](/environment-variables#mcp)