MCP API Reference

Overview

The MCP API provides programmatic access to manage Model Context Protocol servers, their tools, and integrations within FlowX.AI. Use these endpoints to automate MCP server configuration, test connections, and manage tool availability.

All API endpoints require proper authentication and authorization. Ensure you have the necessary permissions to access Integration Management APIs.

Base URL

https://{your-domain}/appmanager/api

Replace {your-domain} with your FlowX.AI deployment domain.

Authentication

All API requests must include authentication headers. The specific authentication mechanism depends on your FlowX.AI deployment configuration. Example Request Headers:

Authorization: Bearer {access_token}
Content-Type: application/json

MCP System Management

Create MCP System

Create a new MCP server connection as a data source.

PATCH /resource/app/{appId}/app-version/{versionId}/rt/system/integration/api/systems

Path Parameters

appId

string

required

The unique identifier of the application.

versionId

string

required

The unique identifier of the application version.

Request Body

action

string

required

The action to perform. Must be CREATE for creating a new system.

resourceName

string

required

The name of the MCP server resource.Validation:

Must be unique within the project
Only letters, numbers, and special characters [], (), ., _, - are allowed

payload

object

required

The configuration payload for the MCP system.

payload.name

string

required

The display name for the MCP server.

payload.type

string

required

The system type. Must be MCP for MCP servers.Allowed values: REST, NOSQL_DB, MCP

payload.baseUrl

string

required

The base URL of the MCP server.Example: https://api.example.com/mcp

payload.authorization

object

required

Authentication configuration for the MCP server.

payload.authorization.type

string

required

The authentication type.Allowed values: NO_AUTH, SERVICE_ACCOUNT

payload.authorization.configuration

object

Authentication configuration details (required when type is not NO_AUTH).

payload.authorization.configuration.clientId

string

OAuth 2.0 client ID (required for SERVICE_ACCOUNT).

payload.authorization.configuration.clientSecret

string

OAuth 2.0 client secret (required for SERVICE_ACCOUNT).

payload.authorization.configuration.identityProviderUrl

string

OAuth 2.0 token endpoint URL (required for SERVICE_ACCOUNT).

payload.description

string

Optional description of the MCP server’s purpose.

Request Example

{
  "action": "CREATE",
  "resourceName": "MCP Server Dev",
  "payload": {
    "name": "MCP Server Dev",
    "type": "MCP",
    "baseUrl": "https://api.example.com/mcp",
    "authorization": {
      "type": "NO_AUTH"
    },
    "description": "Development MCP server for testing"
  }
}

Response

{
  "id": "67dc055c6dee8b54350a386f",
  "flowxUuid": null,
  "resourceId": "0d0a9504-ec98-4931-91ee-a82fd21ddee9",
  "resourceDefinitionId": "84df13b5-b91f-49f2-9cc6-5a739a4d6b1f",
  "type": "MCP",
  "name": "MCP Production Server",
  "baseUrl": "https://api.example.com/mcp",
  "authorization": {
    "type": "SERVICE_ACCOUNT",
    "configuration": {
      "clientId": "mcp-client-123",
      "identityProviderUrl": "https://auth.example.com/oauth/token"
    }
  },
  "description": "Production MCP server with OAuth authentication",
  "tools": [],
  "createdDate": "2025-03-20T12:09:00.757+00:00",
  "modifiedDate": "2025-03-20T12:09:00.757+00:00",
  "createdBy": {
    "firstName": "John",
    "lastName": "Doe",
    "userName": "[email protected]"
  },
  "modifiedBy": {
    "firstName": "John",
    "lastName": "Doe",
    "userName": "[email protected]"
  }
}

string

The unique identifier of the created MCP system.

resourceId

string

The resource identifier used for referencing this system.

resourceDefinitionId

string

The resource definition identifier.

type

string

The system type, always MCP for MCP servers.

tools

array

Array of available tools. Initially empty; populated after connection test.

Client secrets are not returned in API responses for security reasons.

Test MCP Connection

Test the connection to an MCP server before or after creating it.

PATCH /runtime-internal/app/{appId}/app-version/{versionId}/rt/system/integrationengine/api/systems/test-mcp-connection

Path Parameters

appId

string

required

The unique identifier of the application.

versionId

string

required

The unique identifier of the application version.

Request Body

baseUrl

string

required

The base URL of the MCP server to test.

authorization

object

required

Authentication configuration to test.

authorization.type

string

required

The authentication type.Allowed values: NO_AUTH, SERVICE_ACCOUNT

authorization.configuration

object

Authentication configuration details (required when type is not NO_AUTH).

Request Example

{
  "baseUrl": "https://api.example.com/mcp",
  "authorization": {
    "type": "NO_AUTH"
  }
}

Response

{
  "status": 200,
  "message": "Connection successful",
  "tools": [
    {
      "name": "get_customer",
      "description": "Retrieve customer information by ID",
      "inputSchema": {
        "type": "object",
        "properties": {
          "customerId": {
            "type": "string",
            "description": "Customer ID"
          }
        },
        "required": ["customerId"]
      }
    }
  ]
}

status

number

HTTP status code: 200 for success, 400/500 for failures.

message

string

Human-readable message describing the result.

tools

array

Array of available tools (only included on successful connection).

Get MCP System Details

Retrieve detailed information about an MCP system, including its tools.

GET /resource/app/{appId}/app-version/{versionId}/rt/system/ri/{systemResourceId}/integration/api/systems/getById

Path Parameters

appId

string

required

The unique identifier of the application.

versionId

string

required

The unique identifier of the application version.

systemResourceId

string

required

The resource ID of the MCP system.

Response

{
  "id": "67d816adacc8b761ebf769e4",
  "flowxUuid": null,
  "resourceId": "fd407b35-aef8-4c1b-bcc1-68ec7b6813a9",
  "resourceDefinitionId": "2380965c-d8a2-4dd6-8db6-c3842893e6f1",
  "type": "MCP",
  "name": "CRM MCP Server",
  "baseUrl": "https://api.crm.com/mcp",
  "authorization": {
    "type": "SERVICE_ACCOUNT",
    "config": {
      "clientId": "mcp-client-123",
      "identityProviderUrl": "https://auth.crm.com/oauth/token"
    }
  },
  "description": "CRM integration via MCP",
  "tools": [
    {
      "id": "67d816adacc8b761ebf769e5",
      "flowxUuid": null,
      "name": "get_customer",
      "description": "Retrieve customer information by ID",
      "inputSchema": {
        "type": "object",
        "properties": {
          "customerId": {
            "type": "string",
            "description": "Customer unique identifier"
          }
        },
        "required": ["customerId"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "customer": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "name": { "type": "string" },
              "email": { "type": "string" }
            }
          }
        }
      },
      "enabled": true
    },
    {
      "id": "67d816adacc8b761ebf769e6",
      "flowxUuid": null,
      "name": "create_ticket",
      "description": "Create a new support ticket",
      "inputSchema": {
        "type": "object",
        "properties": {
          "customerId": { "type": "string" },
          "subject": { "type": "string" },
          "description": { "type": "string" },
          "priority": { 
            "type": "string",
            "enum": ["low", "medium", "high", "urgent"]
          }
        },
        "required": ["customerId", "subject", "description"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "ticketId": { "type": "string" },
          "status": { "type": "string" }
        }
      },
      "enabled": true
    }
  ],
  "createdDate": "2025-03-17T12:33:49.928+00:00",
  "modifiedDate": "2025-03-17T12:33:49.928+00:00",
  "createdBy": {
    "firstName": "John",
    "lastName": "Doe",
    "userName": "[email protected]",
    "impersonatingUser": null
  },
  "modifiedBy": {
    "firstName": "John",
    "lastName": "Doe",
    "userName": "[email protected]",
    "impersonatingUser": null
  }
}

Get All Systems

Retrieve information about all available systems, including MCP servers, filtered by type.

GET /resource/app/{appId}/app-version/{versionId}/rt/system/include-dep-res/integration/api/systems/all/info?includeManifestInfo=true&depTypes=LIB

Path Parameters

appId

string

required

The unique identifier of the application.

versionId

string

required

The unique identifier of the application version.

Query Parameters

includeManifestInfo

boolean

default:"false"

Whether to include manifest information in the response.

depTypes

string

Comma-separated list of dependency types to include (e.g., LIB).

Response

{
  "systems": [
    {
      "id": "67dc055c6dee8b54350a386f",
      "resourceId": "0d0a9504-ec98-4931-91ee-a82fd21ddee9",
      "resourceDefinitionId": "84df13b5-b91f-49f2-9cc6-5a739a4d6b1f",
      "type": "MCP",
      "name": "CRM MCP Server",
      "description": "CRM integration",
      "appId": "bdc6f918-db15-45c4-b235-0fad617c62d1",
      "appVersionId": "1470fecc-b72e-40f6-90c1-faa41d6feed1"
    },
    {
      "id": "67dc055c6dee8b54350a387a",
      "resourceId": "1d0a9504-ec98-4931-91ee-a82fd21ddee0",
      "resourceDefinitionId": "94df13b5-b91f-49f2-9cc6-5a739a4d6b20",
      "type": "REST",
      "name": "Payment API",
      "description": "Payment gateway integration",
      "appId": "bdc6f918-db15-45c4-b235-0fad617c62d1",
      "appVersionId": "1470fecc-b72e-40f6-90c1-faa41d6feed1"
    }
  ]
}

This endpoint returns all system types (REST, NOSQL_DB, MCP). Filter by the type field to identify MCP servers.

Tool Management

Enable/Disable MCP Tool

Enable or disable a specific tool from an MCP server.

PATCH /resource/app/{appId}/app-version/{versionId}/rt/system/ri/{systemResourceId}/integration/api/systems/ri/{systemId}/tool/{toolId}/enable

Path Parameters

appId

string

required

The unique identifier of the application.

versionId

string

required

The unique identifier of the application version.

systemResourceId

string

required

The resource ID of the MCP system.

systemId

string

required

The ID of the MCP system.

toolId

string

required

The ID of the tool to enable or disable.

Request Body

enabled

boolean

required

Set to true to enable the tool, false to disable it.

Request Example

{
  "enabled": true
}

Response

{
  "status": 200,
  "message": "Tool status updated successfully",
  "tool": {
    "id": "67d816adacc8b761ebf769e5",
    "name": "get_customer",
    "enabled": true
  }
}

status

number

HTTP status code.

message

string

Human-readable message describing the result.

tool

object

The updated tool object with its new status.

Disabling a tool that is currently used in active workflows may affect those workflows. Always verify tool usage before disabling.

Workflow Node Configuration

Custom Agent Node Structure

When creating or updating a Custom Agent node in a workflow, use the following structure:

{
  "id": "68d3d53d01fda29bdf47a732",
  "flowxUuid": "0dae77fa-8d91-4bc8-8b7f-3fade460c684",
  "type": "CUSTOM_AGENT",
  "name": "Custom Agent Node",
  "layoutOptions": {
    "y": 0,
    "x": 0
  },
  "conditions": [],
  "outgoingSequences": [],
  "inputBody": "{}",
  "outputBody": null,
  "payload": null,
  "responseKey": "agentResponse",
  "aiOptions": {
    "aiType": "CUSTOM_AGENT",
    "aiSubType": null,
    "operationPrompt": "Retrieve customer information for ${application.customerId}",
    "exampleOutputJsonSchema": {
      "type": "object",
      "properties": {
        "customer": {
          "type": "object",
          "properties": {
            "id": { "type": "string" },
            "name": { "type": "string" }
          }
        }
      }
    },
    "mcpServers": [
      {
        "resourceDefinitionId": "0d0a9504-ec98-4931-91ee-a82fd21ddee9",
        "appId": "bdc6f918-db15-45c4-b235-0fad617c62d1"
      }
    ]
  },
  "workflowResourceId": "06a8c8b6-d413-42a1-a415-83d650129a34",
  "subWorkflowResourceDefinitionId": null,
  "subWorkflowNodeType": null,
  "createdDate": "2025-03-24T11:25:49.038+00:00",
  "modifiedDate": "2025-03-24T11:25:49.038+00:00",
  "createdBy": {
    "firstName": "John",
    "lastName": "Doe",
    "userName": "[email protected]",
    "impersonatingUser": null
  },
  "modifiedBy": {
    "firstName": "John",
    "lastName": "Doe",
    "userName": "[email protected]",
    "impersonatingUser": null
  }
}

The mcpServers array in aiOptions references MCP systems by their resourceDefinitionId and appId, allowing the Custom Agent to access enabled tools from those servers.

Error Codes

Common HTTP status codes returned by MCP APIs:

Status Code	Description
200	Success - Request completed successfully
201	Created - Resource created successfully
400	Bad Request - Invalid request parameters or validation errors
401	Unauthorized - Authentication required or failed
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
409	Conflict - Resource already exists (e.g., duplicate name)
500	Internal Server Error - Server-side error occurred

Common Error Messages

Name Validation Errors

Error: “Name must be unique inside the project.”Cause: An MCP system with this name already exists in the project.Solution: Choose a different, unique name.

Error: “Name can only contain letters, numbers and the following special characters [] () . _ -”Cause: The name contains invalid special characters.Solution: Remove or replace invalid characters with allowed ones.

Connection Errors

Error: “Connection failed: Invalid authentication credentials”Cause: The provided authentication credentials are incorrect or expired.Solution: Verify the client ID, client secret, and identity provider URL.

Error: “Connection failed: MCP server is unreachable”Cause: The MCP server is down or the URL is incorrect.Solution: Verify the server URL and ensure the server is running.

Authorization Errors

Error: “Insufficient permissions to access Integration Management”Cause: Your user account doesn’t have the required permissions.Solution: Contact your administrator to grant Integration Management access rights.

Rate Limiting

Rate limiting policies depend on your FlowX.AI deployment configuration. Contact your system administrator for specific rate limit details.

Next steps

Add MCP Data Source

Learn how to configure MCP servers via UI

Custom Agent Node

Use MCP tools in Integration Designer workflows

MCP Integration Overview

Learn about MCP integration capabilities

Integration Designer

Learn about Integration Designer and data sources

Getting Started

Platform overview

FlowX.AI Designer

Building projects

Building blocks

Platform deep dive

API reference

​Overview

​Base URL

​Authentication

​MCP System Management

​Create MCP System

​Path Parameters

​Request Body

​Request Example

​Response

​Test MCP Connection

​Path Parameters

​Request Body

​Request Example

​Response

​Get MCP System Details

​Path Parameters

​Response

​Get All Systems

​Path Parameters

​Query Parameters

​Response

​Tool Management

​Enable/Disable MCP Tool

​Path Parameters

​Request Body

​Request Example

​Response

​Workflow Node Configuration

​Custom Agent Node Structure

​Error Codes

​Common Error Messages

​Rate Limiting

​Next steps

Add MCP Data Source

Custom Agent Node

​Related resources

MCP Integration Overview

Integration Designer

Overview

Base URL

Authentication

MCP System Management

Create MCP System

Path Parameters

Request Body

Request Example

Response

Test MCP Connection

Path Parameters

Request Body

Request Example

Response

Get MCP System Details

Path Parameters

Response

Get All Systems

Path Parameters

Query Parameters

Response

Tool Management

Enable/Disable MCP Tool

Path Parameters

Request Body

Request Example

Response

Workflow Node Configuration

Custom Agent Node Structure

Error Codes

Common Error Messages

Rate Limiting

Next steps

Related resources