> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Data Sources

> Learn how to add, configure, and manage MCP servers as data sources in Integration Designer.

## Overview

This guide covers the complete lifecycle of working with MCP (Model Context Protocol) data sources in Integration Designer—from initial setup through ongoing tool management. Once configured, the MCP server's tools become available for use in Custom Agent nodes within your workflows.

## Prerequisites

Before adding an MCP data source, ensure you have:

* Access to Integration Designer with appropriate permissions
* MCP server URL and connection details
* Authentication credentials (if required)
* Knowledge of which tools you want to enable

<Info>
  Ensure you have the necessary permissions to access Integration Designer and manage data sources.
</Info>

## Adding an MCP server

### Step 1: Access Integration Designer

1. Open **FlowX Designer** and navigate to **General Settings**.
2. Select **Integration Designer** from the menu.
3. Click **Add Data Source**.

### Step 2: Select MCP server type

1. In the data source type selection, choose **MCP Server**.
2. A configuration form appears with required fields.

<Frame>
  ![Add MCP Data Source](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp.png)
</Frame>

### Step 3: Configure basic information

<Steps>
  <Step title="Enter Name">
    Provide a unique name for the MCP server connection.
  </Step>

  <Step title="Add Description">
    (Optional) Provide a description of the MCP server's purpose and the tools it provides.

    This description is displayed in the MCP server details page and helps team members understand the integration's purpose.

    <Info>
      If not provided, the description will be autofillled after test connection is successful.
    </Info>
  </Step>

  <Step title="Configure Server URL">
    Enter the base URL of the MCP server.

    **Requirements:**

    * **Required**: URL cannot be empty
    * **Format**: Must be a valid URL (e.g., `https://api.example.com/mcp`)
    * **Multiple Connections**: You can create multiple connections to the same MCP server with different configurations

    **Example URLs:**

    ```
    https://api.githubcopilot.com/mcp/
    https://mcp.figma.com/mcp
    https://mcp.intercom.com/sse
    ```
  </Step>
</Steps>

<Frame>
  ![MCP Server Basic Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp1.png)
</Frame>

### Step 4: Configure authentication

Select the appropriate authentication method for your MCP server:

<Tabs>
  <Tab title="None">
    No authentication required. The MCP server accepts requests without credentials.

    **Use case**: Development environments, public MCP servers, or servers with network-level security.

    **Configuration**: No additional fields required.
  </Tab>

  <Tab title="Basic Auth">
    Username and password authentication.

    **Use case**: MCP servers with simple authentication requirements.

    **Required fields:**

    <ParamField path="username" type="string" required>
      The username for authentication.
    </ParamField>

    <ParamField path="password" type="string" required>
      The password for authentication. Stored securely.
    </ParamField>
  </Tab>

  <Tab title="Bearer Token">
    Static token-based authentication sent in the Authorization header.

    **Use case**: MCP servers that accept pre-generated access tokens or API keys.

    **Required fields:**

    <ParamField path="token" type="string" required>
      The bearer token value. Stored securely.
    </ParamField>
  </Tab>

  <Tab title="API Key">
    Key-based authentication sent via a header or query parameter.

    **Use case**: Third-party API services that use API key authentication.

    **Required fields:**

    <ParamField path="apiKey" type="string" required>
      The API key value. Stored securely.
    </ParamField>
  </Tab>

  <Tab title="OAuth2 Client Credentials">
    OAuth 2.0 service account authentication using the **client credentials flow**.

    **Use case**: Production environments requiring secure service-to-service authentication.

    **Required fields:**

    <ParamField path="clientId" type="string" required>
      The OAuth 2.0 client identifier provided by your identity provider.
    </ParamField>

    <ParamField path="clientSecret" type="string" required>
      The OAuth 2.0 client secret. This is encrypted and stored securely.
    </ParamField>

    <ParamField path="identityProviderUrl" type="string" required>
      The URL of your OAuth 2.0 authorization server (e.g., `https://auth.example.com/oauth/token`).
    </ParamField>

    <Frame>
      ![MCP Service Account Authentication](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp3.png)
    </Frame>
  </Tab>

  <Tab title="OAuth2 User">
    OAuth 2.0 authentication that carries user identity context, using a redirect URI for authorization.

    **Use case**: Operations that require the end-user's identity for access control or auditing.

    **Required fields:**

    <ParamField path="clientId" type="string" required>
      The OAuth 2.0 client identifier.
    </ParamField>

    <ParamField path="clientSecret" type="string" required>
      The OAuth 2.0 client secret.
    </ParamField>

    <ParamField path="identityProviderUrl" type="string" required>
      The authorization server endpoint.
    </ParamField>

    <ParamField path="redirectUri" type="string" required>
      The redirect URI for the OAuth2 authorization flow.
    </ParamField>
  </Tab>
</Tabs>

### Step 5: Test connection

Before saving the MCP data source, test the connection to verify it's configured correctly.

1. Click **Test Connection** button.
2. The system attempts to connect to the MCP server using the provided configuration.
3. Wait for the connection test result:

**Success Response:**

```json theme={"system"}
{
  "status": 200,
  "message": "Connection successful"
}
```

<Check>
  If the connection test succeeds, you can proceed to save the data source. If it fails, review the error message and verify your configuration.
</Check>

<Frame>
  ![Successful Connection Test](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp4.png)
</Frame>

### Step 6: Save and view tools

1. After a successful connection test, click **Create**.
2. The MCP server is persisted as a data source.
3. You are automatically redirected to the MCP server details page, where available tools are displayed.

<Info>
  By default, all tools exposed by the MCP server are enabled. You can turn off specific tools from the MCP server details page.
</Info>

## MCP server details page

After successfully adding an MCP server, the details page displays:

### Header Information

* **Title**: The name you assigned to the MCP server
* **Subtitle**: Description and server URL (trimmed to one row)
  * Click to view full description in a modal

<Frame>
  ![MCP Server Details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp5.png)
</Frame>

### Tools tab

The Tools tab displays all available tools from the MCP server and allows you to manage which tools are available for use in Custom Agent nodes.

<Frame>
  ![MCP Tools Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp6.png)
</Frame>

#### Understanding tool information

Each tool in the MCP server displays the following information:

<ParamField path="name" type="string">
  The unique identifier for the tool. This name is used when the AI agent invokes the tool.
</ParamField>

<ParamField path="description" type="string">
  A brief description of what the tool does. This helps users understand the tool's purpose and when to use it.
</ParamField>

<ParamField path="status" type="boolean">
  Indicates whether the tool is currently enabled (available to AI agents) or disabled (not available).

  * **Enabled**: Tool can be used in Custom Agent nodes
  * **Disabled**: Tool is hidden from Custom Agent node configuration
</ParamField>

#### Viewing tool details

To view complete details about a tool:

1. Click on any tool row in the Tools tab
2. A modal window opens displaying:

<Accordion title="Tool Name">
  The complete name of the tool as registered in the MCP server.
</Accordion>

<Accordion title="Description">
  Full description of the tool's functionality, including:

  * What the tool does
  * When to use it
  * Expected behavior
</Accordion>

<Frame>
  ![MCP Tool Details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp6.png)
</Frame>

<Accordion title="Input Schema">
  JSON Schema defining the expected input parameters for the tool.

  **Example:**

  ```json theme={"system"}
    {
      "type": "object",
      "properties": {
        "customerId": {
          "type": "string",
          "description": "The unique identifier for the customer"
        },
        "includeOrders": {
          "type": "boolean",
          "description": "Whether to include order history",
          "default": false
        }
      },
      "required": ["customerId"]
    }
  ```

  <Info>
    The input schema is used by AI agents to understand what parameters the tool expects and how to format requests.
  </Info>
</Accordion>

<Accordion title="Output Schema (Optional)">
  JSON Schema defining the structure of the tool's response.

  **Example:**

  ```json theme={"system"}
    {
      "type": "object",
      "properties": {
        "customer": {
          "type": "object",
          "properties": {
            "id": { "type": "string" },
            "name": { "type": "string" },
            "email": { "type": "string" }
          }
        },
        "orders": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "orderId": { "type": "string" },
              "total": { "type": "number" }
            }
          }
        }
      }
    }
  ```

  <Info>
    Output schemas are optional. If not provided, the AI agent will work with the actual response structure returned by the tool.
  </Info>
</Accordion>

<Frame>
  ![MCP Tool Details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp7.png)
</Frame>

#### Enabling and disabling tools

You can control which tools are available for use in Custom Agent nodes by enabling or disabling them.

**Enable/Disable Individual Tools:**

<Steps>
  <Step title="Access Tool Menu">
    In the Tools tab, locate the tool you want to enable or disable.
  </Step>

  <Step title="Toggle Tool Status">
    * Click the three-dot menu (⋯) at the end of the tool row
    * Select **Enable** or **Disable** from the menu
  </Step>

  <Step title="Confirm Change">
    The tool's status updates immediately. Enabled tools show a green status indicator, while disabled tools show a gray indicator.
  </Step>
</Steps>

<Frame>
  ![Enable/Disable Tools Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp8.png)
</Frame>

<Warning>
  Disabling tools that are currently in use by active workflows may affect those workflows. Always verify that tools are not in use before disabling them.
</Warning>

### Authorization tab

The Authorization tab displays the current authentication configuration:

* **Authentication Type**: None, Basic Auth, Bearer Token, API Key, OAuth2 Client Credentials, or OAuth2 User
* **Configuration Details**: Relevant fields for the selected auth type (sensitive information like secrets and tokens are hidden)

<Warning>
  Changes to authentication settings require re-testing the connection and may affect existing workflows using this MCP server.
</Warning>

<Frame>
  ![Authorization Tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp9.png)
</Frame>

## Managing tools

### Refreshing tools from MCP server

Tools are automatically synchronized from the MCP server when you:

* Initially connect the MCP server
* Re-test the connection from the Authorization tab
* Manually refresh the tools list

To manually refresh tools:

1. Navigate to the MCP server details page
2. Go to the **Authorization** tab
3. Click **Check for Updates**
4. If successful, return to the **Tools** tab to see any new or updated tools

<Info>
  Tool definitions (name, description, schemas) are read-only and managed by the MCP server. You can only control the enabled/disabled status from Integration Designer.
</Info>

### API endpoint for tool management

Tools can also be managed programmatically using the API:

**Enable/Disable Tool API:**

```http theme={"system"}
POST /api/systems/tool/{toolId}/enable?resourceId={resourceId}
```

Required header: `X-Workspace-Id: {workspaceId}`

**Request Body:**

```json theme={"system"}
{
  "enabled": true
}
```

**Response:**

```json theme={"system"}
{
  "status": 200,
  "message": "Tool status updated successfully",
  "tool": {
    "id": "67d816adacc8b761ebf769e5",
    "name": "get_customer",
    "enabled": true
  }
}
```

<Info>
  For complete API documentation, see [MCP API Reference](../../../api/mcp-api-reference).
</Info>

### Monitoring tool usage

To understand which tools are being used in your workflows:

1. Navigate to the **Run Logs** section after running a workflow
2. Check the **Tools** tab (visible when MCP tools are used)
3. Review which tools were invoked and their execution details

<Frame>
  ![Tool Usage Monitoring](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/run_logs.png)
</Frame>

## Managing multiple MCP connections

You can create multiple connections to the same MCP server with different configurations:

**Use Cases:**

* Different authentication credentials for different environments
* Separate tool configurations for different use cases
* Testing vs. production instances

**Example:**

```
- CRM Production (https://api.crm.com) - Service Account Auth
- CRM Development (https://api.crm.com) - No Auth
- CRM Testing (https://api.crm.com) - Different Service Account
```

## Validation rules summary

<Accordion title="Name Validation">
  * **Required**: ✅ Yes
  * **Unique**: ✅ Within project
  * **Allowed Characters**: Letters, numbers, `[]`, `()`, `.`, `_`, `-`
  * **Error Message**: "Name must be unique inside the project." or "Name can only contain letters, numbers and the following special characters \[] () . \_ -"
</Accordion>

<Accordion title="Description Validation">
  * **Required**: ❌ No
  * **Max Length**: No explicit limit (trimmed in UI display)
</Accordion>

<Accordion title="Server URL Validation">
  * **Required**: ✅ Yes
  * **Unique**: ❌ No (multiple connections allowed)
  * **Format**: Valid URL with protocol (http/https)
</Accordion>

<Accordion title="Authentication Validation">
  * **Required Fields**: Depends on authentication type selected
  * **Service Account**: All three fields (Client ID, Client Secret, Identity Provider URL) are required
</Accordion>

## Best practices

### Data source setup

<Check>
  **Test Before Saving**: Always test the connection before saving an MCP data source to ensure the configuration is correct.
</Check>

<Check>
  **Use Descriptive Names**: Choose clear, descriptive names that indicate the MCP server's purpose and environment (e.g., "CRM-Production", "Analytics-Dev").
</Check>

<Check>
  **Document Purpose**: Add detailed descriptions to help team members understand what the MCP server provides and when to use it.
</Check>

<Check>
  **Secure Authentication**: Use Service Account authentication for production environments to ensure secure access.
</Check>

### Tool management

<Check>
  **Start with All Enabled**: By default, all tools are enabled. Review the available tools and disable only those you don't need.
</Check>

<Check>
  **Regular Audits**: Periodically review enabled tools to ensure they're still needed and being used effectively.
</Check>

<Check>
  **Security Considerations**: Disable tools that provide access to sensitive data or operations if they're not needed for your use case.
</Check>

### Workflow impact considerations

Before disabling tools, consider the following:

1. **Check Tool Usage**: Verify if the tool is currently used in any active workflows
2. **Impact Assessment**: Understand what workflows might be affected
3. **Communication**: Notify team members before disabling tools that might be in use
4. **Testing**: Test workflows after re-enabling tools to ensure they work as expected

<Warning>
  If you disable a tool that's referenced in a Custom Agent node, that node will not be able to use the tool during execution. The AI agent will work with the remaining enabled tools only.
</Warning>

## Common issues and troubleshooting

<AccordionGroup>
  <Accordion title="Connection Test Fails">
    **Possible Causes:**

    * Invalid server URL
    * Incorrect authentication credentials
    * Network connectivity issues
    * MCP server is down or unreachable

    **Solutions:**

    * Verify the server URL is correct and accessible
    * Check authentication credentials with your MCP server administrator
    * Test network connectivity to the MCP server
    * Confirm the MCP server is running and accepting connections
  </Accordion>

  <Accordion title="No Tools Displayed">
    **Possible Causes:**

    * MCP server hasn't exposed any tools
    * Connection issue after initial setup

    **Solutions:**

    * Verify the MCP server is configured to expose tools
    * Re-test the connection from the Authorization tab
    * Contact your MCP server administrator
  </Accordion>

  <Accordion title="Name Validation Error">
    **Error**: "Name must be unique inside the project."

    **Solution**: Choose a different name that hasn't been used in this project.

    ***

    **Error**: "Name can only contain letters, numbers and the following special characters \[] () . \_ -"

    **Solution**: Remove any special characters that aren't in the allowed list.
  </Accordion>

  <Accordion title="New Tools Not Appearing">
    **Problem**: You added new tools to your MCP server, but they don't appear in Integration Designer.

    **Solution**:

    1. Go to the Authorization tab
    2. Click **Test Connection** to refresh the tool list
    3. Return to the Tools tab to see the new tools
  </Accordion>

  <Accordion title="Tool Used in Active Workflow">
    **Problem**: You want to disable a tool, but it's used in an active workflow.

    **Solution**:

    1. Search for workflows using the tool
    2. Update those workflows to use alternative tools or remove the MCP server reference
    3. Test the modified workflows
    4. Disable the tool once it's no longer in use
  </Accordion>

  <Accordion title="Re-enabling a Previously Disabled Tool">
    **Problem**: You disabled a tool and now need to re-enable it.

    **Solution**:

    1. Find the tool in the Tools tab (disabled tools are still listed)
    2. Click the toggle or menu to enable it
    3. Test workflows that use this tool to ensure they work correctly
  </Accordion>

  <Accordion title="Tool Schema Changes">
    **Problem**: The MCP server updated a tool's input or output schema.

    **Solution**:

    1. Test the MCP connection to refresh tool definitions
    2. Review the updated schema in the tool details modal
    3. Update any Custom Agent nodes that use this tool to match the new schema
    4. Test affected workflows
  </Accordion>
</AccordionGroup>

## Next steps

<Card title="Custom Agent Node" href="../custom-agent-node" icon="robot">
  Learn how to use MCP tools in workflows with Custom Agent nodes
</Card>

## Related resources

<CardGroup cols={2}>
  <Card title="MCP Integration Overview" href="./mcp-integration-overview" icon="link">
    Learn about MCP integration capabilities
  </Card>

  <Card title="MCP API Reference" href="../../../api/mcp-api-reference" icon="code">
    View API documentation for programmatic access
  </Card>

  <Card title="Integration Designer course" icon="graduation-cap" href="https://academy.flowx.ai/explore/integration-designer">
    Hands-on course covering data sources including MCP server integration
  </Card>
</CardGroup>