> ## 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](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview).
</Warning>

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

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

## Base URL

```text theme={"system"}
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={"system"}
Authorization: Bearer {access_token}
Content-Type: application/json
```

## MCP System Management

### Create MCP System

Create a new MCP server connection as a data source.

<RequestExample>
  ```http theme={"system"}
  PATCH /resource/app/{appId}/app-version/{versionId}/rt/system/integration/api/systems
  ```
</RequestExample>

#### Path Parameters

<ParamField path="appId" type="string" required>
  The unique identifier of the application.
</ParamField>

<ParamField path="versionId" type="string" required>
  The unique identifier of the application version.
</ParamField>

#### Request Body

<ParamField body="action" type="string" required>
  The action to perform. Must be `CREATE` for creating a new system.
</ParamField>

<ParamField body="resourceName" type="string" required>
  The name of the MCP server resource.

  **Validation:**

  * Must be unique within the project
  * Only letters, numbers, and special characters `[]`, `()`, `.`, `_`, `-` are allowed
</ParamField>

<ParamField body="payload" type="object" required>
  The configuration payload for the MCP system.
</ParamField>

<ParamField body="payload.name" type="string" required>
  The display name for the MCP server.
</ParamField>

<ParamField body="payload.type" type="string" required>
  The system type. Must be `MCP` for MCP servers.

  **Allowed values:** `REST`, `NOSQL_DB`, `MCP`
</ParamField>

<ParamField body="payload.baseUrl" type="string" required>
  The base URL of the MCP server.

  **Example:** `https://api.example.com/mcp`
</ParamField>

<ParamField body="payload.authorization" type="object" required>
  Authentication configuration for the MCP server.
</ParamField>

<ParamField body="payload.authorization.type" type="string" required>
  The authentication type.

  **Allowed values:** `NO_AUTH`, `SERVICE_ACCOUNT`
</ParamField>

<ParamField body="payload.authorization.configuration" type="object">
  Authentication configuration details (required when type is not `NO_AUTH`).
</ParamField>

<ParamField body="payload.authorization.configuration.clientId" type="string">
  OAuth 2.0 client ID (required for `SERVICE_ACCOUNT`).
</ParamField>

<ParamField body="payload.authorization.configuration.clientSecret" type="string">
  OAuth 2.0 client secret (required for `SERVICE_ACCOUNT`).
</ParamField>

<ParamField body="payload.authorization.configuration.identityProviderUrl" type="string">
  OAuth 2.0 token endpoint URL (required for `SERVICE_ACCOUNT`).
</ParamField>

<ParamField body="payload.description" type="string">
  Optional description of the MCP server's purpose.
</ParamField>

#### Request Example

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

#### Response

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

<ResponseField name="id" type="string">
  The unique identifier of the created MCP system.
</ResponseField>

<ResponseField name="resourceId" type="string">
  The resource identifier used for referencing this system.
</ResponseField>

<ResponseField name="resourceDefinitionId" type="string">
  The resource definition identifier.
</ResponseField>

<ResponseField name="type" type="string">
  The system type, always `MCP` for MCP servers.
</ResponseField>

<ResponseField name="tools" type="array">
  Array of available tools. Initially empty; populated after connection test.
</ResponseField>

<Note>
  Client secrets are not returned in API responses for security reasons.
</Note>

***

### Test MCP Connection

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

<RequestExample>
  ```http theme={"system"}
  PATCH /runtime-internal/app/{appId}/app-version/{versionId}/rt/system/integrationengine/api/systems/test-mcp-connection
  ```
</RequestExample>

#### Path Parameters

<ParamField path="appId" type="string" required>
  The unique identifier of the application.
</ParamField>

<ParamField path="versionId" type="string" required>
  The unique identifier of the application version.
</ParamField>

#### Request Body

<ParamField body="baseUrl" type="string" required>
  The base URL of the MCP server to test.
</ParamField>

<ParamField body="authorization" type="object" required>
  Authentication configuration to test.
</ParamField>

<ParamField body="authorization.type" type="string" required>
  The authentication type.

  **Allowed values:** `NO_AUTH`, `SERVICE_ACCOUNT`
</ParamField>

<ParamField body="authorization.configuration" type="object">
  Authentication configuration details (required when type is not `NO_AUTH`).
</ParamField>

#### Request Example

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

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

#### Response

<ResponseExample>
  ```json 200 Success theme={"system"}
  {
    "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={"system"}
  {
    "status": 400,
    "message": "Connection failed: Invalid authentication credentials"
  }
  ```

  ```json 500 Server Error theme={"system"}
  {
    "status": 500,
    "message": "Connection failed: MCP server is unreachable"
  }
  ```
</ResponseExample>

<ResponseField name="status" type="number">
  HTTP status code: 200 for success, 400/500 for failures.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable message describing the result.
</ResponseField>

<ResponseField name="tools" type="array">
  Array of available tools (only included on successful connection).
</ResponseField>

***

### Get MCP System Details

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

<RequestExample>
  ```http theme={"system"}
  GET /resource/app/{appId}/app-version/{versionId}/rt/system/ri/{systemResourceId}/integration/api/systems/getById
  ```
</RequestExample>

#### Path Parameters

<ParamField path="appId" type="string" required>
  The unique identifier of the application.
</ParamField>

<ParamField path="versionId" type="string" required>
  The unique identifier of the application version.
</ParamField>

<ParamField path="systemResourceId" type="string" required>
  The resource ID of the MCP system.
</ParamField>

#### Response

<ResponseExample>
  ```json 200 Success theme={"system"}
  {
    "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={"system"}
  {
    "status": 404,
    "error": "Not Found",
    "message": "MCP system with ID 'invalid-id' not found"
  }
  ```
</ResponseExample>

***

### Get All Systems

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

<RequestExample>
  ```http theme={"system"}
  GET /resource/app/{appId}/app-version/{versionId}/rt/system/include-dep-res/integration/api/systems/all/info?includeManifestInfo=true&depTypes=LIB
  ```
</RequestExample>

#### Path Parameters

<ParamField path="appId" type="string" required>
  The unique identifier of the application.
</ParamField>

<ParamField path="versionId" type="string" required>
  The unique identifier of the application version.
</ParamField>

#### Query Parameters

<ParamField query="includeManifestInfo" type="boolean" default="false">
  Whether to include manifest information in the response.
</ParamField>

<ParamField query="depTypes" type="string">
  Comma-separated list of dependency types to include (e.g., `LIB`).
</ParamField>

#### Response

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

<Info>
  This endpoint returns all system types (REST, NOSQL\_DB, MCP). Filter by the `type` field to identify MCP servers.
</Info>

***

## Tool Management

### Enable/Disable MCP Tool

Enable or disable a specific tool from an MCP server.

<RequestExample>
  ```http theme={"system"}
  PATCH /resource/app/{appId}/app-version/{versionId}/rt/system/ri/{systemResourceId}/integration/api/systems/ri/{systemId}/tool/{toolId}/enable
  ```
</RequestExample>

#### Path Parameters

<ParamField path="appId" type="string" required>
  The unique identifier of the application.
</ParamField>

<ParamField path="versionId" type="string" required>
  The unique identifier of the application version.
</ParamField>

<ParamField path="systemResourceId" type="string" required>
  The resource ID of the MCP system.
</ParamField>

<ParamField path="systemId" type="string" required>
  The ID of the MCP system.
</ParamField>

<ParamField path="toolId" type="string" required>
  The ID of the tool to enable or disable.
</ParamField>

#### Request Body

<ParamField body="enabled" type="boolean" required>
  Set to `true` to enable the tool, `false` to disable it.
</ParamField>

#### Request Example

<CodeGroup>
  ```json Enable Tool theme={"system"}
  {
    "enabled": true
  }
  ```

  ```json Disable Tool theme={"system"}
  {
    "enabled": false
  }
  ```
</CodeGroup>

#### Response

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

  ```json 404 Not Found theme={"system"}
  {
    "status": 404,
    "error": "Not Found",
    "message": "Tool with ID '67d816adacc8b761ebf769e5' not found"
  }
  ```
</ResponseExample>

<ResponseField name="status" type="number">
  HTTP status code.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable message describing the result.
</ResponseField>

<ResponseField name="tool" type="object">
  The updated tool object with its new status.
</ResponseField>

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

***

## Workflow Node Configuration

### Custom Agent Node Structure

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

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

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

***

## 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 title="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>

<Accordion title="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>

<Accordion title="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.
</Accordion>

## Rate Limiting

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

## Next steps

<CardGroup cols={2}>
  <Card title="Add MCP Data Source" href="../platform-deep-dive/integrations/mcp-integration/adding-mcp-data-source" icon="plug">
    Learn how to configure MCP servers via UI
  </Card>

  <Card title="Custom Agent Node" href="../platform-deep-dive/integrations/custom-agent-node" icon="robot">
    Use MCP tools in Integration Designer workflows
  </Card>
</CardGroup>

## Related resources

<Card title="MCP Integration Overview" href="../platform-deep-dive/integrations/mcp-integration/mcp-integration-overview" icon="link">
  Learn about MCP integration capabilities
</Card>

<Card title="Integration Designer" href="../platform-deep-dive/integrations/integration-designer" icon="link">
  Learn about Integration Designer and data sources
</Card>


## Related topics

- [MCP integration](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview.md)
- [MCP Data Sources](/5.9/docs/platform-deep-dive/integrations/mcp-integration/adding-mcp-data-source.md)
- [Custom Components](/5.9/docs/building-blocks/reusable-resources/custom-components.md)
- [FlowX.AI 5.9.0 Release Notes](/release-notes/v5.x/v5.9.0-june-2026/v5.9.0-june-2026.md)
- [FlowX.AI 5.3.0 Release Notes](/release-notes/v5.x/v5.3.0-december-2025/v5.3.0-december-2025.md)