> ## 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 API Reference

> Complete API documentation for managing MCP servers, tools, and integrations programmatically.

> [!WARNING]
>
> **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](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview.md).

## 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.

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

## Base URL

```text theme={"dark"}
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:**

```http theme={"dark"}
Authorization: Bearer {access_token}
Content-Type: application/json
```

## MCP System Management

### Create MCP System

Create a new MCP server connection as a data source.

```http theme={"dark"}
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

```json No Authentication theme={"dark"}
{
  "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"
  }
}
```

```json Service Account Authentication theme={"dark"}
{
  "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

```json 201 Created theme={"dark"}
{
  "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"
  }
}
```

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

```json 400 Validation Error theme={"dark"}
{
  "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"
}
```

**id** `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.

> [!NOTE]
>
> 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.

```http theme={"dark"}
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

```json No Authentication theme={"dark"}
{
  "baseUrl": "https://api.example.com/mcp",
  "authorization": {
    "type": "NO_AUTH"
  }
}
```

```json Service Account Authentication theme={"dark"}
{
  "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

```json 200 Success theme={"dark"}
{
  "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"]
      }
    }
  ]
}
```

```json 400 Connection Failed theme={"dark"}
{
  "status": 400,
  "message": "Connection failed: Invalid authentication credentials"
}
```

```json 500 Server Error theme={"dark"}
{
  "status": 500,
  "message": "Connection failed: MCP server is unreachable"
}
```

**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.

```http theme={"dark"}
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

```json 200 Success theme={"dark"}
{
  "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
  }
}
```

```json 404 Not Found theme={"dark"}
{
  "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.

```http theme={"dark"}
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

```json 200 Success theme={"dark"}
{
  "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"
    }
  ]
}
```

> [!NOTE]
>
> 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.

```http theme={"dark"}
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

```json Enable Tool theme={"dark"}
{
  "enabled": true
}
```

```json Disable Tool theme={"dark"}
{
  "enabled": false
}
```

#### Response

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

```json 404 Not Found theme={"dark"}
{
  "status": 404,
  "error": "Not Found",
  "message": "Tool with ID '67d816adacc8b761ebf769e5' not found"
}
```

**status** `number`

HTTP status code.

**message** `string`

Human-readable message describing the result.

**tool** `object`

The updated tool object with its new status.

> [!WARNING]
>
> 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:

```json theme={"dark"}
{
  "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
  }
}
```

> [!NOTE]
>
> 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

> [accordion] 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.

> [accordion] 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.

> [accordion] 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

> [!NOTE]
>
> Rate limiting policies depend on your FlowX.AI deployment configuration. Contact your system administrator for specific rate limit details.

## Next steps

> [card] [Add MCP Data Source](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/mcp-integration/adding-mcp-data-source.md)
>
> Learn how to configure MCP servers via UI

> [card] [Custom Agent Node](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/custom-agent-node.md)
>
> Use MCP tools in Integration Designer workflows

## Related resources

> [card] [MCP Integration Overview](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview.md)
>
> Learn about MCP integration capabilities

> [card] [Integration Designer](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/integration-designer.md)
>
> Learn about Integration Designer and data sources


## Related topics

- [MCP integration](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview.md)
- [MCP Data Sources](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/mcp-integration/adding-mcp-data-source.md)
- [FlowX.AI 5.9.0 Release Notes](https://docs.flowx.ai/release-notes/v5.x/v5.9.0-june-2026/v5.9.0-june-2026.md)
- [FlowX.AI 5.3.0 Release Notes](https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/v5.3.0-december-2025.md)
- [Integration Designer](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/integration-designer.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.