Product UpdatesStatus PageWorkato Academy
English
Get a trial
Developer API
Resources

# MCP Servers

Use this resource to manage MCP (Model Context Protocol) servers programmatically.

# Quick reference

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

# List MCP servers

Returns a list of MCP servers in the workspace.

GET /api/mcp/mcp_servers

# 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/mcp/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

Creates a new MCP server in the workspace.

POST /api/mcp/mcp_servers

# 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 used with workato_recipe_function and workato_api_platform tools. id is a string handle when used with workato_genie tools.

# Sample request

curl  -X POST https://www.workato.com/api/mcp/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

Retrieves details for a specific MCP server.

GET /api/mcp/mcp_servers/:handle

# URL parameters

Name Type Description
handle string
required		 MCP server handle.

# Sample request

curl  -X GET 'https://www.workato.com/api/mcp/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

Updates an existing MCP server.

PUT /api/mcp/mcp_servers/:handle

# URL parameters

Name Type Description
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/mcp/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

Deletes an MCP server.

DELETE /api/mcp/mcp_servers/:handle

# URL parameters

Name Type Description
handle string
required		 MCP server handle.

# Sample request

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

# Sample response

Returns 204 No Content on success.

# Renew MCP server authentication token

Generates a new authentication token for an MCP server 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/mcp/mcp_servers/:handle/token_renew

# URL parameters

Name Type Description
handle string
required		 MCP server handle.

# Sample request

curl  -X POST 'https://www.workato.com/api/mcp/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

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

POST /api/mcp/mcp_servers/:handle/assign_tools

# URL parameters

Name Type Description
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/mcp/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

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

POST /api/mcp/mcp_servers/:handle/assign_user_groups

# URL parameters

Name Type Description
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/mcp/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

Removes identity provider user groups from an MCP server.

POST /api/mcp/mcp_servers/:handle/remove_user_groups

# URL parameters

Name Type Description
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/mcp/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

Moves an MCP server to a specified folder.

PUT /api/mcp/mcp_servers/:handle/update_folder

# URL parameters

Name Type Description
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/mcp/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 with the new folder_id reflected in created_at and updated_at timestamps.

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

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

GET /api/mcp/mcp_servers/:mcp_server_handle/server_policies

# URL parameters

Name Type Description
mcp_server_handle string
required		 MCP server handle.

# Sample request

curl  -X GET 'https://www.workato.com/api/mcp/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

Updates the security policy configuration, including IP for an MCP server.

PUT /api/mcp/mcp_servers/:mcp_server_handle/server_policies

# URL parameters

Name Type Description
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/mcp/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

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

GET /api/mcp/mcp_servers/:mcp_server_handle/tools

# URL parameters

Name Type Description
mcp_server_handle string
required		 MCP server handle.

# Query parameters

Name Type Description
vua_required boolean
optional		 Filter by whether Verified User Access (VUA) 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/mcp/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

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

PUT /api/mcp/mcp_servers/:mcp_server_handle/tools/:id

# URL parameters

Name Type Description
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/mcp/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

Removes a tool from an MCP server.

API ENDPOINTS CAN'T BE DELETED

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

DELETE /api/mcp/mcp_servers/:mcp_server_handle/tools/:id

# URL parameters

Name Type Description
mcp_server_handle string
required		 MCP server handle.
id number
required		 Tool ID.

# Sample request

curl  -X DELETE 'https://www.workato.com/api/mcp/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

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

GET /api/mcp/user_groups

# 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/mcp/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
}
← Delete a row
On-prem →


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

On this page