MCP API Reference

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

{
  "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": "john.doe@example.com"
  },
  "modifiedBy": {
    "firstName": "John",
    "lastName": "Doe",
    "userName": "john.doe@example.com"
  }
}

{
  "status": 400,
  "error": "Bad Request",
  "message": "Name must be unique inside the project.",
  "timestamp": "2025-03-20T12:09:00.757+00:00"
}

{
  "status": 400,
  "error": "Bad Request",
  "message": "Name can only contain letters, numbers and the following special characters [] () . _ -",
  "timestamp": "2025-03-20T12:09:00.757+00:00"
}

Reference under review. The endpoints documented on this page use /resource/.../runtime-internal/... and similar internal paths. They are not part of the public integration API and may change between releases without notice. For supported MCP setup, see MCP Integration overview.

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

string

required

The unique identifier of the application.

string

required

The unique identifier of the application version.

Request Body

string

required

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

string

required

The name of the MCP server resource.Validation:

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

object

required

The configuration payload for the MCP system.

string

required

The display name for the MCP server.

string

required

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

string

required

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

object

required

Authentication configuration for the MCP server.

string

required

The authentication type.Allowed values: NO_AUTH, SERVICE_ACCOUNT

object

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

string

OAuth 2.0 client ID (required for SERVICE_ACCOUNT).

string

OAuth 2.0 client secret (required for SERVICE_ACCOUNT).

string

OAuth 2.0 token endpoint URL (required for SERVICE_ACCOUNT).

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"
  }
}

{
  "action": "CREATE",
  "resourceName": "MCP Production Server",
  "payload": {
    "name": "MCP Production Server",
    "type": "MCP",
    "baseUrl": "https://api.example.com/mcp",
    "authorization": {
      "type": "SERVICE_ACCOUNT",
      "configuration": {
        "clientId": "mcp-client-123",
        "clientSecret": "your-secret-key",
        "identityProviderUrl": "https://auth.example.com/oauth/token"
      }
    },
    "description": "Production MCP server with OAuth authentication"
  }
}

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": "john.doe@example.com"
  },
  "modifiedBy": {
    "firstName": "John",
    "lastName": "Doe",
    "userName": "john.doe@example.com"
  }
}

{
  "status": 400,
  "error": "Bad Request",
  "message": "Name must be unique inside the project.",
  "timestamp": "2025-03-20T12:09:00.757+00:00"
}

{
  "status": 400,
  "error": "Bad Request",
  "message": "Name can only contain letters, numbers and the following special characters [] () . _ -",
  "timestamp": "2025-03-20T12:09:00.757+00:00"
}

string

The unique identifier of the created MCP system.

string

The resource identifier used for referencing this system.

string

The resource definition identifier.

string

The system type, always MCP for MCP servers.

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

string

required

The unique identifier of the application.

string

required

The unique identifier of the application version.

Request Body

string

required

The base URL of the MCP server to test.

object

required

Authentication configuration to test.

string

required

The authentication type.Allowed values: NO_AUTH, SERVICE_ACCOUNT

object

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

Request Example

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

{
  "baseUrl": "https://api.example.com/mcp",
  "authorization": {
    "type": "SERVICE_ACCOUNT",
    "configuration": {
      "clientId": "mcp-client-123",
      "clientSecret": "your-secret-key",
      "identityProviderUrl": "https://auth.example.com/oauth/token"
    }
  }
}

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": 400,
  "message": "Connection failed: Invalid authentication credentials"
}

{
  "status": 500,
  "message": "Connection failed: MCP server is unreachable"
}

number

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

string

Human-readable message describing the result.

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

string

required

The unique identifier of the application.

string

required

The unique identifier of the application version.

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": "john.doe@example.com",
    "impersonatingUser": null
  },
  "modifiedBy": {
    "firstName": "John",
    "lastName": "Doe",
    "userName": "john.doe@example.com",
    "impersonatingUser": null
  }
}

{
  "status": 404,
  "error": "Not Found",
  "message": "MCP system with ID 'invalid-id' not found"
}

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

string

required

The unique identifier of the application.

string

required

The unique identifier of the application version.

Query Parameters

boolean

default:"false"

Whether to include manifest information in the response.

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

string

required

The unique identifier of the application.

string

required

The unique identifier of the application version.

string

required

The resource ID of the MCP system.

string

required

The ID of the MCP system.

string

required

The ID of the tool to enable or disable.

Request Body

boolean

required

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

Request Example

{
  "enabled": true
}

{
  "enabled": false
}

Response

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

{
  "status": 404,
  "error": "Not Found",
  "message": "Tool with ID '67d816adacc8b761ebf769e5' not found"
}

number

HTTP status code.

string

Human-readable message describing the result.

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": "john.doe@example.com",
    "impersonatingUser": null
  },
  "modifiedBy": {
    "firstName": "John",
    "lastName": "Doe",
    "userName": "john.doe@example.com",
    "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

Last modified on May 12, 2026

​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