Embedded API - 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.
GET	/api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/access_assignments	List MCP access assignments in a customer workspace.
POST	/api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/access_assignments	Create an MCP access assignment in a customer workspace.
GET	/api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/access_assignments/:id	Retrieve an MCP access assignment in a customer workspace.
PUT	/api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/access_assignments/:id	Update an MCP access assignment in a customer workspace.
DELETE	/api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/access_assignments/:id	Delete an MCP access assignment in a customer workspace.

List MCP servers in a customer workspace

Returns a list of MCP servers in a customer workspace.

GET https://YOUR_DATA_CENTER/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

shell

curl  -X GET 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers?folder_id=:folder_id' \
      -H 'Authorization: Bearer <api_token>'

Sample response

json

{
    "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 https://YOUR_DATA_CENTER/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

shell

curl  -X POST 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": ":name",
            "description": ":description",
            "folder_id": :folder_id,
            "tools": [
              {
                "trigger_application": ":trigger_application",
                "id": ":id"
              }
            ]
          }'

Sample response

json

{
    "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 https://YOUR_DATA_CENTER/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. You can find the `mcp_server_handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.

Sample request

shell

curl  -X GET 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:handle' \
      -H 'Authorization: Bearer <api_token>'

Sample response

json

{
    "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 https://YOUR_DATA_CENTER/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. You can find the `mcp_server_handle in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is` mcps-AxbxNxNz-wsB-SM `if the URL is` https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.

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

shell

curl  -X PUT 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:handle' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": ":name",
            "description": ":description",
            "auth_type": ":auth_type"
          }'

Sample response

json

{
    "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 https://YOUR_DATA_CENTER/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. You can find the `mcp_server_handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.

Sample request

shell

curl  -X DELETE 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:handle' \
      -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 https://YOUR_DATA_CENTER/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. You can find the `handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.

Sample request

shell

curl  -X POST 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:handle/token_renew' \
      -H 'Authorization: Bearer <api_token>'

Sample response

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

json

{
    "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 https://YOUR_DATA_CENTER/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. You can find the `handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.

Payload

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

Sample request

shell

curl  -X POST 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:handle/assign_tools' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "tools": [
              {
                "trigger_application": ":trigger_application_1",
                "id": ":id_1"
              },
              {
                "trigger_application": ":trigger_application_2",
                "id": ":id_2"
              }
            ]
          }'

Sample response

Returns the updated MCP server object.

json

{
    "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 https://YOUR_DATA_CENTER/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. You can find the `handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.

Payload

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

Sample request

shell

curl  -X POST 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:handle/assign_user_groups' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "idp_user_group_ids": [":idp_user_group_ids_1", ":idp_user_group_ids_2"]
          }'

Sample response

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

json

{
    "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 https://YOUR_DATA_CENTER/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. You can find the `handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.

Payload

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

Sample request

shell

curl  -X POST 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:handle/remove_user_groups' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "idp_user_group_ids": [":idp_user_group_ids"]
          }'

Sample response

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

json

{
    "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 https://YOUR_DATA_CENTER/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. You can find the `handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.

Payload

Name	Type	Description
folder_id	number required	Target folder ID.

Sample request

shell

curl  -X PUT 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:handle/update_folder' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "folder_id": :folder_id
          }'

Sample response

Returns the updated MCP server object reflecting the new folder.

json

{
    "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, usage limits, Classless Inter-Domain Routing (CIDR), and IP addresses.

GET https://YOUR_DATA_CENTER/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. You can find the `mcp_server_handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.

Sample request

shell

curl  -X GET 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/server_policies' \
      -H 'Authorization: Bearer <api_token>'

Sample response

json

{
    "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 https://YOUR_DATA_CENTER/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. You can find the `mcp_server_handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.

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 limits 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

shell

curl  -X PUT 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/server_policies' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "mcp_server_policy": {
              "rate_limits": { "per_minute": :per_minute },
              "quota_limits": { "per_day": :per_day },
              "ip_allow_list": [":ip_allow_list_1", ":ip_allow_list_2"],
              "ip_deny_list": []
            }
          }'

Sample response

json

{
    "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 https://YOUR_DATA_CENTER/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. You can find the `mcp_server_handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.

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

shell

curl  -X GET 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/tools' \
      -H 'Authorization: Bearer <api_token>'

Sample response

json

{
    "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 https://YOUR_DATA_CENTER/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. You can find the `mcp_server_handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.
id	number required	Tool ID.

Payload

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

Sample request

shell

curl  -X PUT 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/tools/:id' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "description": ":description"
          }'

Sample response

json

{
    "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 https://YOUR_DATA_CENTER/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. You can find the `mcp_server_handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.
id	number required	Tool ID.

Sample request

shell

curl  -X DELETE 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/tools/:id' \
      -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.

THIS ISN'T THE COLLABORATOR GROUPS RESOURCE

The user groups on this endpoint aren't RBAC collaborator groups. Use the /api/v2/managed_users/:managed_user_id/user_groups endpoints to manage collaborator groups.

GET https://YOUR_DATA_CENTER/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

shell

curl  -X GET 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/user_groups' \
      -H 'Authorization: Bearer <api_token>'

Sample response

json

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

MCP access assignments

MCP access assignments control tool-level role-based access control (RBAC) for an MCP server in a customer workspace. Each assignment grants one identity provider user or user group access to either all tools on the server or a specific set of tools.

REQUIREMENTS AND LIMITATIONS

Access assignments work only with MCP servers that use workato_idp as the auth_type.
Access assignments don't work with api_collection-based MCP servers.
An identity can have only one access assignment per server.

List MCP access assignments in a customer workspace

Returns a paginated list of MCP server access assignments for users or user groups in a customer workspace.

Required privilege: oem_mcp_access_assignments.index.

GET https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/access_assignments

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. You can find the `mcp_server_handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.

Query parameters

Name	Type	Description
identity_type	string required	Identity type. Accepted values: `user`, `user_group`.
search	string optional	Search identity names.
order	string optional	Sort by identity name. Accepted values: `asc`, `desc`. Defaults to `asc`.
page	integer optional	Positive page number. Defaults to 1.
per_page	integer optional	Number of items per page, from 1 to 100. Defaults to 100.

Sample request

shell

curl  -X GET 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/mcps-7Hk9pQ2r-aB3-1a/access_assignments?identity_type=user_group&page=1&per_page=100' \
      -H 'Authorization: Bearer <api_token>'

Sample response

Returns 200 OK.

json

{
    "data": [
        {
            "id": "mcpsaa-7Hk9pQ2s-aB3cD4-1a",
            "idp_user_id": null,
            "idp_user_group_id": "group-abc123",
            "all_tools": false,
            "tool_ids": [3001, 3002],
            "created_at": "2026-10-09T10:00:00.000Z",
            "updated_at": "2026-10-09T10:00:00.000Z"
        },
        {
            "id": "mcpsaa-7Hk9pQ2u-jK7mN8-1a",
            "idp_user_id": null,
            "idp_user_group_id": "group-def456",
            "all_tools": true,
            "tool_ids": [],
            "created_at": "2026-10-09T10:00:00.000Z",
            "updated_at": "2026-10-09T10:00:00.000Z"
        }
    ],
    "count": 2,
    "page": 1,
    "per_page": 100
}

The example lists group assignments. Each assignment has a string idp_user_id and a null idp_user_group_id when identity_type is user. Both identity fields are present by default.

Create an MCP access assignment in a customer workspace

Creates one access assignment for a user or user group on an MCP server in a customer workspace.

Required privilege: oem_mcp_access_assignments.create.

POST https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/access_assignments

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. You can find the `mcp_server_handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.

Payload

Name	Type	Description
idp_user_id	string conditional	Non-empty identity provider user ID. Supply exactly one of `idp_user_id` or `idp_user_group_id`.
idp_user_group_id	string conditional	Non-empty identity provider user group ID. Supply exactly one of `idp_user_id` or `idp_user_group_id`.
all_tools	boolean optional	Grant access to all tools on the server. Defaults to `false`.
tool_ids	array of integers conditional	Required and non-empty when `all_tools` is `false` or omitted. When `all_tools` is `true`, omit this field or send an empty array. Every ID must belong to this server. Use the List tools endpoint to retrieve tool IDs.

Additional constraints

The identity must be available in the target environment.
An identity can have only one assignment per server.
Tool IDs refer to the server's MCP tool records, not recipe IDs or API endpoint IDs.

Sample request

shell

curl  -X POST 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/mcps-7Hk9pQ2r-aB3-1a/access_assignments' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "idp_user_group_id": "group-abc123",
            "all_tools": false,
            "tool_ids": [3001, 3002]
          }'

Use the following request body to grant a user access to all tools:

json

{
    "idp_user_id": "user-abc123",
    "all_tools": true
}

Sample response

Returns 201 Created.

json

{
    "data": {
        "id": "mcpsaa-7Hk9pQ2s-aB3cD4-1a",
        "idp_user_id": null,
        "idp_user_group_id": "group-abc123",
        "all_tools": false,
        "tool_ids": [3001, 3002],
        "created_at": "2026-10-09T10:00:00.000Z",
        "updated_at": "2026-10-09T10:00:00.000Z"
    }
}

The server generates the assignment ID. Tool IDs are deduplicated and sorted.

Get an MCP access assignment in a customer workspace

Retrieves an access assignment belonging to an MCP server in a customer workspace.

Required privilege: oem_mcp_access_assignments.show.

GET https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/access_assignments/: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. You can find the `mcp_server_handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.
id	string required	Access assignment ID belonging to this server.

This endpoint doesn't accept query or body parameters.

Sample request

shell

curl  -X GET 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/mcps-7Hk9pQ2r-aB3-1a/access_assignments/mcpsaa-7Hk9pQ2s-aB3cD4-1a' \
      -H 'Authorization: Bearer <api_token>'

Sample response

Returns 200 OK.

json

{
    "data": {
        "id": "mcpsaa-7Hk9pQ2s-aB3cD4-1a",
        "idp_user_id": null,
        "idp_user_group_id": "group-abc123",
        "all_tools": false,
        "tool_ids": [3001, 3002],
        "created_at": "2026-10-09T10:00:00.000Z",
        "updated_at": "2026-10-09T10:00:00.000Z"
    }
}

idp_user_id contains the user ID and idp_user_group_id is null for user assignments. Both fields are present by default. Assignments that grant all tools have all_tools: true and tool_ids: [].

Update an MCP access assignment in a customer workspace

Replaces the tool access scope of an existing MCP server access assignment in a customer workspace.

Required privilege: oem_mcp_access_assignments.update.

PUT https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/access_assignments/:id

This path also accepts PATCH with the same replacement behavior.

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. You can find the `mcp_server_handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.
id	string required	Access assignment ID belonging to this server.

Payload

Name	Type	Description
all_tools	boolean optional	Grant access to all tools on the server. Defaults to `false` when omitted.
tool_ids	array of integers conditional	Required and non-empty when `all_tools` is `false` or omitted. When `all_tools` is `true`, omit this field or send an empty array. Every ID must belong to this server.

UPDATES REPLACE THE ENTIRE TOOL SCOPE

Provide at least one of all_tools or tool_ids. Omitted fields aren't retained. An omitted all_tools defaults to false, and an omitted tool_ids defaults to an empty array. You can't change the identity on an existing assignment.

Sample request

shell

curl  -X PUT 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/mcps-7Hk9pQ2r-aB3-1a/access_assignments/mcpsaa-7Hk9pQ2s-aB3cD4-1a' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "all_tools": false,
            "tool_ids": [3001]
          }'

To grant all tools, send {"all_tools": true}. The response then contains all_tools: true and tool_ids: [].

Sample response

Returns 200 OK.

json

{
    "data": {
        "id": "mcpsaa-7Hk9pQ2s-aB3cD4-1a",
        "idp_user_id": null,
        "idp_user_group_id": "group-abc123",
        "all_tools": false,
        "tool_ids": [3001],
        "created_at": "2026-10-09T10:00:00.000Z",
        "updated_at": "2026-10-09T11:00:00.000Z"
    }
}

The assignment identity and creation timestamp don't change.

Delete an MCP access assignment in a customer workspace

Deletes a user's or user group's access assignment from an MCP server in a customer workspace.

Required privilege: oem_mcp_access_assignments.destroy.

DELETE https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/:mcp_server_handle/access_assignments/: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. You can find the `mcp_server_handle` in the URL when you go to AI Hub > Enterprise MCP and select the MCP server you plan to use. For example, your MCP server handle is `mcps-AxbxNxNz-wsB-SM` if the URL is `https://app.workato.com/mcp/mcps-AxbxNxNz-wsB-SM/overview`.
id	string required	Access assignment ID belonging to this server.

This endpoint doesn't accept query or body parameters.

Sample request

shell

curl  -X DELETE 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/mcp_servers/mcps-7Hk9pQ2r-aB3-1a/access_assignments/mcpsaa-7Hk9pQ2s-aB3cD4-1a' \
      -H 'Authorization: Bearer <api_token>'

Sample response

Returns 204 No Content on success, with an empty response body.

Last updated:

Embedded API - MCP servers ​

Quick reference ​

List MCP servers in a customer workspace ​

URL parameters ​

Query parameters ​

Sample request ​

Sample response ​

Create an MCP server in a customer workspace ​

URL parameters ​

Payload ​

Sample request ​

Sample response ​

Get MCP server details in a customer workspace ​

URL parameters ​

Sample request ​

Sample response ​

Update an MCP server in a customer workspace ​

URL parameters ​

Payload ​

Sample request ​

Sample response ​

Delete an MCP server in a customer workspace ​

URL parameters ​

Sample request ​

Sample response ​

Renew MCP server authentication token in a customer workspace ​

URL parameters ​

Sample request ​

Sample response ​

Assign tools to an MCP server in a customer workspace ​

URL parameters ​

Payload ​

Sample request ​

Sample response ​

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

URL parameters ​

Payload ​

Sample request ​

Sample response ​

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

URL parameters ​

Payload ​

Sample request ​

Sample response ​

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

URL parameters ​

Payload ​

Sample request ​

Sample response ​

Get server policy configuration in a customer workspace ​

URL parameters ​

Sample request ​

Sample response ​

Update server policy configuration in a customer workspace ​

URL parameters ​

Payload ​

Sample request ​

Sample response ​

List tools for an MCP server in a customer workspace ​

URL parameters ​

Query parameters ​

Sample request ​

Sample response ​

Update tool description in a customer workspace ​

URL parameters ​

Payload ​

Sample request ​

Sample response ​

Delete a tool in a customer workspace ​

URL parameters ​

Sample request ​

Sample response ​

List identity provider user groups in a customer workspace ​

URL parameters ​

Query parameters ​

Sample request ​

Sample response ​

MCP access assignments ​

List MCP access assignments in a customer workspace ​

URL parameters ​

Embedded API - MCP servers

Quick reference

List MCP servers in a customer workspace

URL parameters

Query parameters

Sample request

Sample response

Create an MCP server in a customer workspace

URL parameters

Payload

Sample request

Sample response

Get MCP server details in a customer workspace

URL parameters

Sample request

Sample response

Update an MCP server in a customer workspace

URL parameters

Payload

Sample request

Sample response

Delete an MCP server in a customer workspace

URL parameters

Sample request

Sample response

Renew MCP server authentication token in a customer workspace

URL parameters

Sample request

Sample response

Assign tools to an MCP server in a customer workspace

URL parameters

Payload

Sample request

Sample response

Assign user groups to an MCP server in a customer workspace

URL parameters

Payload

Sample request

Sample response

Remove user groups from an MCP server in a customer workspace

URL parameters

Payload

Sample request

Sample response

Move MCP server to a different folder in a customer workspace

URL parameters

Payload

Sample request

Sample response

Get server policy configuration in a customer workspace

URL parameters

Sample request

Sample response

Update server policy configuration in a customer workspace

URL parameters

Payload

Sample request

Sample response

List tools for an MCP server in a customer workspace

URL parameters

Query parameters

Sample request

Sample response

Update tool description in a customer workspace

URL parameters

Payload

Sample request

Sample response

Delete a tool in a customer workspace

URL parameters

Sample request

Sample response

List identity provider user groups in a customer workspace

URL parameters

Query parameters

Sample request

Sample response

MCP access assignments

List MCP access assignments in a customer workspace

URL parameters