Product UpdatesStatus PageWorkato Academy
English
Get a trial
Embedded API
Resources

# MCP Servers

Use these resources to programmatically manage MCP (Model Context Protocol) servers in customer workspaces.

# Quick reference

Type Resource Description
GET /api/managed_users/:managed_user_id/
mcp_servers		 List MCP servers in a customer workspace.
POST /api/managed_users/:managed_user_id/
mcp_servers		 Create an MCP server in a customer workspace.
GET /api/managed_users/:managed_user_id/
mcp_servers/:handle		 Retrieve MCP server details in a customer workspace.
PUT /api/managed_users/:managed_user_id/
mcp_servers/:handle		 Update an MCP server in a customer workspace.
DELETE /api/managed_users/:managed_user_id/
mcp_servers/:handle		 Delete an MCP server in a customer workspace.
POST /api/managed_users/:managed_user_id/
mcp_servers/:handle/token_renew		 Renew an MCP server authentication token in a customer workspace.
POST /api/managed_users/:managed_user_id/
mcp_servers/:handle/assign_tools		 Assign tools to an MCP server in a customer workspace.
POST /api/managed_users/:managed_user_id/
mcp_servers/:handle/assign_user_groups		 Assign user groups to an MCP server in a customer workspace.
POST /api/managed_users/:managed_user_id/
mcp_servers/:handle/remove_user_groups		 Remove user groups from an MCP server in a customer workspace.
PUT /api/managed_users/:managed_user_id/
mcp_servers/:handle/update_folder		 Move an MCP server to a different folder in a customer workspace.
GET /api/managed_users/:managed_user_id/
mcp_servers/:mcp_server_handle/server_policies		 Retrieve server policy configuration in a customer workspace.
PUT /api/managed_users/:managed_user_id/
mcp_servers/:mcp_server_handle/server_policies		 Update server policy configuration in a customer workspace.
GET /api/managed_users/:managed_user_id/
mcp_servers/:mcp_server_handle/tools		 List tools for an MCP server in a customer workspace.
PUT /api/managed_users/:managed_user_id/
mcp_servers/:mcp_server_handle/tools/:id		 Update tool description in a customer workspace.
DELETE /api/managed_users/:managed_user_id/
mcp_servers/:mcp_server_handle/tools/:id		 Delete a tool in a customer workspace.
GET /api/managed_users/:managed_user_id/
user_groups		 List identity provider user groups in a customer workspace.

# List MCP servers in a customer workspace

Returns a list of MCP servers in a customer workspace.

GET /api/managed_users/:managed_user_id/mcp_servers

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.

# Query parameters

Name Type Description
project_id number
optional		 Filter by project ID.
folder_id number
optional		 Filter by folder ID.
authentication_method string
optional		 Filter by authentication method. Accepted values: token, workato_idp.
page number
optional		 Page number. Defaults to 1.
per_page number
optional		 Number of items per page. Maximum is 50.

# Sample request

curl  -X GET 'https://www.workato.com/api/managed_users/91829/mcp_servers?folder_id=27180380' \
      -H 'Authorization: Bearer <api_token>'

# Sample response

{
    "data": [
        {
            "id": 1001,
            "name": "Sales Tools MCP Server",
            "description": "Provides CRM and deal management tools for AI clients",
            "folder_id": 27180380,
            "project_id": 13595198,
            "authentication_method": "token",
            "tools_count": 5
        },
        {
            "id": 1002,
            "name": "HR Automation Server",
            "description": "HR onboarding and employee management tools",
            "folder_id": 27180380,
            "project_id": 13595198,
            "authentication_method": "workato_idp",
            "tools_count": 3
        }
    ],
    "count": 2,
    "page": 1,
    "per_page": 50
}

# Create an MCP server in a customer workspace

Creates a new MCP server in a customer workspace.

POST /api/managed_users/:managed_user_id/mcp_servers

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.

# Payload

Name Type Description
name string
required		 Server name.
folder_id number
required		 Folder ID for the MCP server.
description string
optional		 Server description.
asset_id number
optional		 API collection ID. Omit to create a project asset server.
tools array of objects
optional		 Tools to assign to the server at creation. Each object requires trigger_application (string) and id (string). id is a number when using workato_recipe_function and workato_api_platform tools. id is a string handle when using workato_genie tools.

# Sample request

curl  -X POST 'https://www.workato.com/api/managed_users/91829/mcp_servers' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Sales Tools MCP Server",
            "description": "Provides CRM and deal management tools for AI clients",
            "folder_id": 27180380,
            "tools": [
              {
                "trigger_application": "workato_api_platform",
                "id": "98231"
              }
            ]
          }'

# Sample response

{
    "data": {
        "id": 1001,
        "name": "Sales Tools MCP Server",
        "description": "Provides CRM and deal management tools for AI clients",
        "asset_type": "api_collection",
        "logo_url": "https://www.workato.com/images/mcp-server-logo.png",
        "tools_count": 1,
        "mcp_url": "https://www.workato.com/mcp/servers/sales-tools-mcp-server?token=abc123xyz",
        "auth_type": "token",
        "idp_user_group_ids": [],
        "api_collection": null,
        "created_at": "2025-10-15T13:41:05.207-07:00",
        "updated_at": "2025-10-15T13:41:05.207-07:00"
    }
}

# Get MCP server details in a customer workspace

Retrieves details for a specific MCP server in a customer workspace.

GET /api/managed_users/:managed_user_id/mcp_servers/:handle

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.
handle string
required		 MCP server handle.

# Sample request

curl  -X GET 'https://www.workato.com/api/managed_users/91829/mcp_servers/sales-tools-mcp-server' \
      -H 'Authorization: Bearer <api_token>'

# Sample response

{
    "data": {
        "id": 1001,
        "name": "Sales Tools MCP Server",
        "description": "Provides CRM and deal management tools for AI clients",
        "asset_type": "api_collection",
        "logo_url": "https://www.workato.com/images/mcp-server-logo.png",
        "tools_count": 5,
        "mcp_url": "https://www.workato.com/mcp/servers/sales-tools-mcp-server?token=abc123xyz",
        "auth_type": "token",
        "idp_user_group_ids": [],
        "api_collection": null,
        "created_at": "2025-10-15T13:41:05.207-07:00",
        "updated_at": "2025-10-16T09:22:11.100-07:00"
    }
}

# Update an MCP server in a customer workspace

Updates an existing MCP server in a customer workspace.

PUT /api/managed_users/:managed_user_id/mcp_servers/:handle

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.
handle string
required		 MCP server handle.

# Payload

Name Type Description
name string
optional		 Server name.
description string
optional		 Server description.
auth_type string
optional		 Authentication type. Accepted values: token, workato_idp.
idp_user_group_ids array of strings
optional		 Identity provider user group IDs that have access to the server. Only applicable when auth_type is workato_idp.
folder_id number
optional		 Target folder ID to move the server.

# Sample request

curl  -X PUT 'https://www.workato.com/api/managed_users/91829/mcp_servers/sales-tools-mcp-server' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Sales & CRM Tools MCP Server",
            "description": "Provides CRM, deal management, and pipeline tools for AI clients",
            "auth_type": "token"
          }'

# Sample response

{
    "data": {
        "id": 1001,
        "name": "Sales & CRM Tools MCP Server",
        "description": "Provides CRM, deal management, and pipeline tools for AI clients",
        "asset_type": "api_collection",
        "logo_url": "https://www.workato.com/images/mcp-server-logo.png",
        "tools_count": 5,
        "mcp_url": "https://www.workato.com/mcp/servers/sales-tools-mcp-server?token=abc123xyz",
        "auth_type": "token",
        "idp_user_group_ids": [],
        "api_collection": null,
        "created_at": "2025-10-15T13:41:05.207-07:00",
        "updated_at": "2025-10-17T11:05:33.812-07:00"
    }
}

# Delete an MCP server in a customer workspace

Deletes an MCP server in a customer workspace.

DELETE /api/managed_users/:managed_user_id/mcp_servers/:handle

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.
handle string
required		 MCP server handle.

# Sample request

curl  -X DELETE 'https://www.workato.com/api/managed_users/91829/mcp_servers/sales-tools-mcp-server' \
      -H 'Authorization: Bearer <api_token>'

# Sample response

Returns 204 No Content on success.

# Renew MCP server authentication token in a customer workspace

Generates a new authentication token for an MCP server in a customer workspace and invalidates the previous token. Use this endpoint to rotate credentials after a security event or as part of a regular credential rotation policy.

POST /api/managed_users/:managed_user_id/mcp_servers/:handle/token_renew

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.
handle string
required		 MCP server handle.

# Sample request

curl  -X POST 'https://www.workato.com/api/managed_users/91829/mcp_servers/sales-tools-mcp-server/token_renew' \
      -H 'Authorization: Bearer <api_token>'

# Sample response

Returns the updated MCP server object with the new mcp_url containing the refreshed token.

{
    "data": {
        "id": 1001,
        "name": "Sales & CRM Tools MCP Server",
        "description": "Provides CRM, deal management, and pipeline tools for AI clients",
        "asset_type": "api_collection",
        "logo_url": "https://www.workato.com/images/mcp-server-logo.png",
        "tools_count": 5,
        "mcp_url": "https://www.workato.com/mcp/servers/sales-tools-mcp-server?token=newtoken789",
        "auth_type": "token",
        "idp_user_group_ids": [],
        "api_collection": null,
        "created_at": "2025-10-15T13:41:05.207-07:00",
        "updated_at": "2025-10-18T08:00:00.000-07:00"
    }
}

# Assign tools to an MCP server in a customer workspace

Assigns one or more tools to an MCP server in a customer workspace. Tools already assigned to the server aren't duplicated.

POST /api/managed_users/:managed_user_id/mcp_servers/:handle/assign_tools

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.
handle string
required		 MCP server handle.

# Payload

Name Type Description
tools array of objects
required		 Tools to assign. Each object requires trigger_application (string) and id (string).

# Sample request

curl  -X POST 'https://www.workato.com/api/managed_users/91829/mcp_servers/sales-tools-mcp-server/assign_tools' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "tools": [
              {
                "trigger_application": "workato_api_platform",
                "id": "98232"
              },
              {
                "trigger_application": "workato_genie",
                "id": "my-genie-handle"
              }
            ]
          }'

# Sample response

Returns the updated MCP server object.

{
    "data": {
        "id": 1001,
        "name": "Sales & CRM Tools MCP Server",
        "description": "Provides CRM, deal management, and pipeline tools for AI clients",
        "asset_type": "api_collection",
        "logo_url": "https://www.workato.com/images/mcp-server-logo.png",
        "tools_count": 7,
        "mcp_url": "https://www.workato.com/mcp/servers/sales-tools-mcp-server?token=newtoken789",
        "auth_type": "token",
        "idp_user_group_ids": [],
        "api_collection": null,
        "created_at": "2025-10-15T13:41:05.207-07:00",
        "updated_at": "2025-10-18T09:15:22.000-07:00"
    }
}

# Assign user groups to an MCP server in a customer workspace

Assigns identity provider user groups to an MCP server in a customer workspace. Only applicable when the server's auth_type is workato_idp.

POST /api/managed_users/:managed_user_id/mcp_servers/:handle/assign_user_groups

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.
handle string
required		 MCP server handle.

# Payload

Name Type Description
idp_user_group_ids array of strings
required		 IDs of the user groups to add.

# Sample request

curl  -X POST 'https://www.workato.com/api/managed_users/91829/mcp_servers/hr-automation-server/assign_user_groups' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "idp_user_group_ids": ["group-abc123", "group-def456"]
          }'

# Sample response

Returns the updated MCP server object with the assigned user group IDs reflected in idp_user_group_ids.

{
    "data": {
        "id": 1002,
        "name": "HR Automation Server",
        "description": "HR onboarding and employee management tools",
        "asset_type": "project_asset",
        "logo_url": "https://www.workato.com/images/mcp-server-logo.png",
        "tools_count": 3,
        "mcp_url": "https://www.workato.com/mcp/servers/hr-automation-server?token=hrtoken456",
        "auth_type": "workato_idp",
        "idp_user_group_ids": ["group-abc123", "group-def456"],
        "api_collection": null,
        "created_at": "2025-10-15T10:00:00.000-07:00",
        "updated_at": "2025-10-18T10:30:00.000-07:00"
    }
}

# Remove user groups from an MCP server in a customer workspace

Removes identity provider user groups from an MCP server in a customer workspace.

POST /api/managed_users/:managed_user_id/mcp_servers/:handle/remove_user_groups

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.
handle string
required		 MCP server handle.

# Payload

Name Type Description
idp_user_group_ids array of strings
required		 IDs of the user groups to remove.

# Sample request

curl  -X POST 'https://www.workato.com/api/managed_users/91829/mcp_servers/hr-automation-server/remove_user_groups' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "idp_user_group_ids": ["group-abc123"]
          }'

# Sample response

Returns the updated MCP server object with the specified groups removed from idp_user_group_ids.

{
    "data": {
        "id": 1002,
        "name": "HR Automation Server",
        "description": "HR onboarding and employee management tools",
        "asset_type": "project_asset",
        "logo_url": "https://www.workato.com/images/mcp-server-logo.png",
        "tools_count": 3,
        "mcp_url": "https://www.workato.com/mcp/servers/hr-automation-server?token=hrtoken456",
        "auth_type": "workato_idp",
        "idp_user_group_ids": ["group-def456"],
        "api_collection": null,
        "created_at": "2025-10-15T10:00:00.000-07:00",
        "updated_at": "2025-10-18T11:00:00.000-07:00"
    }
}

# Move MCP server to a different folder in a customer workspace

Moves an MCP server to a specified folder in a customer workspace.

PUT /api/managed_users/:managed_user_id/mcp_servers/:handle/update_folder

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.
handle string
required		 MCP server handle.

# Payload

Name Type Description
folder_id number
required		 Target folder ID.

# Sample request

curl  -X PUT 'https://www.workato.com/api/managed_users/91829/mcp_servers/hr-automation-server/update_folder' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "folder_id": 27180399
          }'

# Sample response

Returns the updated MCP server object reflecting the new folder.

{
    "data": {
        "id": 1002,
        "name": "HR Automation Server",
        "description": "HR onboarding and employee management tools",
        "asset_type": "project_asset",
        "logo_url": "https://www.workato.com/images/mcp-server-logo.png",
        "tools_count": 3,
        "mcp_url": "https://www.workato.com/mcp/servers/hr-automation-server?token=hrtoken456",
        "auth_type": "workato_idp",
        "idp_user_group_ids": ["group-def456"],
        "api_collection": null,
        "created_at": "2025-10-15T10:00:00.000-07:00",
        "updated_at": "2025-10-18T12:00:00.000-07:00"
    }
}

# Get server policy configuration in a customer workspace

Retrieves the security policy configuration for an MCP server, including rate limits, quota limits, Classless Inter-Domain Routing (CIDR), and IP addresses.

GET /api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/server_policies

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.
mcp_server_handle string
required		 MCP server handle.

# Sample request

curl  -X GET 'https://www.workato.com/api/managed_users/91829/mcp_servers/sales-tools-mcp-server/server_policies' \
      -H 'Authorization: Bearer <api_token>'

# Sample response

{
    "id": 501,
    "mcp_server_id": 1001,
    "rate_limits": {
        "per_minute": 60
    },
    "quota_limits": {
        "per_day": 10000
    },
    "ip_allow_list": ["203.0.113.0/24"],
    "ip_deny_list": [],
    "created_at": "2025-10-15T13:41:05.207-07:00",
    "updated_at": "2025-10-16T09:22:11.100-07:00"
}

# Update server policy configuration in a customer workspace

Updates the security policy configuration for an MCP server in a customer workspace.

PUT /api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/server_policies

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.
mcp_server_handle string
required		 MCP server handle.

# Payload

Name Type Description
mcp_server_policy object
required		 Policy configuration object.
mcp_server_policy[rate_limits] object
optional		 Rate limit configurations.
mcp_server_policy[quota_limits] object
optional		 Quota limit configurations.
mcp_server_policy[ip_allow_list] array of strings
optional		 IP addresses or CIDR ranges to allow.
mcp_server_policy[ip_deny_list] array of strings
optional		 IP addresses or CIDR ranges to deny.

# Sample request

curl  -X PUT 'https://www.workato.com/api/managed_users/91829/mcp_servers/sales-tools-mcp-server/server_policies' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "mcp_server_policy": {
              "rate_limits": { "per_minute": 30 },
              "quota_limits": { "per_day": 5000 },
              "ip_allow_list": ["203.0.113.0/24", "198.51.100.42"],
              "ip_deny_list": []
            }
          }'

# Sample response

{
    "id": 501,
    "mcp_server_id": 1001,
    "rate_limits": {
        "per_minute": 30
    },
    "quota_limits": {
        "per_day": 5000
    },
    "ip_allow_list": ["203.0.113.0/24", "198.51.100.42"],
    "ip_deny_list": [],
    "created_at": "2025-10-15T13:41:05.207-07:00",
    "updated_at": "2025-10-18T14:00:00.000-07:00"
}

# List tools for an MCP server in a customer workspace

Returns a paginated list of tools assigned to an MCP server in a customer workspace.

GET /api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/tools

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.
mcp_server_handle string
required		 MCP server handle.

# Query parameters

Name Type Description
vua_required boolean
optional		 Filter by whether VUA (Verified User Authentication) is required.
search string
optional		 Search term to filter tools by name.
page number
optional		 Page number. Defaults to 1.
per_page number
optional		 Number of items per page. Defaults to 100. Maximum is 100.

# Sample request

curl  -X GET 'https://www.workato.com/api/managed_users/91829/mcp_servers/sales-tools-mcp-server/tools' \
      -H 'Authorization: Bearer <api_token>'

# Sample response

{
    "data": [
        {
            "id": 3001,
            "name": "Create Salesforce Lead",
            "description": "Creates a new lead record in Salesforce CRM",
            "trigger_application": "workato_api_platform",
            "action_applications": ["salesforce"],
            "flow_id": 66870001,
            "vua_required": false
        },
        {
            "id": 3002,
            "name": "Send Deal Notification",
            "description": "Sends a Slack notification when a deal stage changes",
            "trigger_application": "workato_recipe_function",
            "action_applications": ["slack"],
            "flow_id": 66870002,
            "vua_required": true
        }
    ],
    "count": 2,
    "page": 1,
    "per_page": 100
}

# Update tool description in a customer workspace

Updates the description of a tool within an MCP server in a customer workspace. This modifies the description shown to AI clients without affecting the underlying recipe or API endpoint.

PUT /api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/tools/:id

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.
mcp_server_handle string
required		 MCP server handle.
id number
required		 Tool ID.

# Payload

Name Type Description
description string
optional		 New description for the tool.

# Sample request

curl  -X PUT 'https://www.workato.com/api/managed_users/91829/mcp_servers/sales-tools-mcp-server/tools/3001' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "description": "Creates a new lead record in Salesforce CRM with name, email, and company details"
          }'

# Sample response

{
    "id": 3001,
    "name": "Create Salesforce Lead",
    "description": "Creates a new lead record in Salesforce CRM with name, email, and company details",
    "trigger_application": "workato_api_platform",
    "action_applications": ["salesforce"],
    "flow_id": 66870001,
    "vua_required": false
}

# Delete a tool in a customer workspace

Removes a tool from an MCP server in a customer workspace.

API ENDPOINTS CAN'T BE DELETED

Only tools backed by recipe functions or Genie agents can be deleted. Attempting to delete an API endpoint tool returns a 400 Bad Request error.

DELETE /api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/tools/:id

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.
mcp_server_handle string
required		 MCP server handle.
id number
required		 Tool ID.

# Sample request

curl  -X DELETE 'https://www.workato.com/api/managed_users/91829/mcp_servers/sales-tools-mcp-server/tools/3002' \
      -H 'Authorization: Bearer <api_token>'

# Sample response

Returns 204 No Content on success.

# List identity provider user groups in a customer workspace

Returns a paginated list of identity provider user groups available in a customer workspace. Use the group IDs from this response when assigning access to MCP servers that use workato_idp authentication.

GET /api/managed_users/:managed_user_id/user_groups

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded customer Account ID or External ID. External IDs must have the prefix E and be URL-encoded. For example, EA2300.

# Query parameters

Name Type Description
page number
optional		 Page number. Defaults to 1.
per_page number
optional		 Number of items per page. Defaults to 100. Maximum is 100.

# Sample request

curl  -X GET 'https://www.workato.com/api/managed_users/91829/user_groups' \
      -H 'Authorization: Bearer <api_token>'

# Sample response

{
    "data": [
        {
            "id": "group-abc123",
            "name": "Sales Team",
            "users_count": 24,
            "created_at": "2025-01-10T08:00:00.000Z",
            "updated_at": "2025-09-15T12:30:00.000Z"
        },
        {
            "id": "group-def456",
            "name": "HR Admins",
            "users_count": 6,
            "created_at": "2025-01-10T08:00:00.000Z",
            "updated_at": "2025-08-20T10:00:00.000Z"
        }
    ],
    "count": 2,
    "page": 1,
    "per_page": 100
}
← Batch unassign a customer category from workspaces
On-prem →


Last updated: 3/3/2026, 6:54:13 PM

On this page