Developer API - MCP servers

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

TOKEN AND HASHED TOKEN AUTHENTICATION

hashed_token is the default authentication type for token-based MCP servers. The token authentication type is considered legacy. Existing servers using token continue to work, but new servers use hashed_token. Refer to Create a hashed token for more information on how to manage tokens on hashed_token servers.

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/:mcp_server_handle/tokens	Create a hashed token.
DELETE	/api/mcp/mcp_servers/:mcp_server_handle/tokens/:id	Delete a hashed token.
POST	/api/mcp/mcp_servers/:mcp_server_handle/tokens/:id/refresh	Refresh a hashed 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.
GET	/api/mcp/mcp_servers/:mcp_server_handle/access_assignments	List MCP access assignments.
POST	/api/mcp/mcp_servers/:mcp_server_handle/access_assignments	Create an MCP access assignment.
GET	/api/mcp/mcp_servers/:mcp_server_handle/access_assignments/:id	Retrieve an MCP access assignment.
PUT	/api/mcp/mcp_servers/:mcp_server_handle/access_assignments/:id	Update an MCP access assignment.
DELETE	/api/mcp/mcp_servers/:mcp_server_handle/access_assignments/:id	Delete an MCP access assignment.

List MCP servers

Returns a list of MCP servers in the workspace.

GET https://YOUR_DATA_CENTER/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: `hashed_token`, `token` (legacy), `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/mcp/mcp_servers?folder_id=:folder_id_value' \
      -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": "hashed_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 https://YOUR_DATA_CENTER/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.

HASHED TOKEN AS DEFAULT AUTH TYPE

MCP servers use hashed_token as the default auth_type unless you specify a different authentication type. Use the MCP hashed tokens endpoints to manage tokens on a hashed_token server.

Sample request

shell

curl  -X POST https://YOUR_DATA_CENTER/api/mcp/mcp_servers \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": ":name",
            "description": ":description",
            "folder_id": :folder_id_value,
            "tools": [
              {
                "trigger_application": ":trigger_application",
                "id": ":tool_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": "hashed_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 https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:handle

URL parameters

Name	Type	Description
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/mcp/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": "hashed_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 https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:handle

URL parameters

Name	Type	Description
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: `hashed_token` (default), `token` (legacy), `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.

LEGACY AUTH TYPE

Workato retains the token auth_type for backward compatibility. New servers should use hashed_token. Create token profiles with the MCP hashed tokens endpoints to switch an existing server's auth_type to hashed_token. hashed_token servers use individually named, revocable token profiles instead of a single server-level token.

Sample request

shell

curl  -X PUT 'https://YOUR_DATA_CENTER/api/mcp/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": "hashed_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 https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:handle

URL parameters

Name	Type	Description
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/mcp/mcp_servers/:handle' \
      -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.

LEGACY ENDPOINT

This endpoint applies to servers using the legacy token auth type, which carry a single server-level token. Use Refresh a hashed token for hashed_token servers, which operates on an individual, named token profile.

POST https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:handle/token_renew

URL parameters

Name	Type	Description
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 POST 'https://YOUR_DATA_CENTER/api/mcp/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"
    }
}

MCP hashed tokens

MCP hashed token endpoints manage individual, named token profiles for MCP servers with hashed_token as the auth_type. This is an update from the the legacy token auth type in which a single server-level token is managed through token renewal. hashed_token supports up to 50 named, independently revocable token profiles per server.

Create a hashed token

Creates a token profile for a server with hashed_token as the auth_type.

MCP servers support a maximum of 50 active hashed tokens.

POST https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:mcp_server_handle/tokens

URL parameters

Name	Type	Description
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
name	string required	Token profile name. Must be non-blank, no longer than 100 characters, and case-insensitively unique among the server's active tokens.

Additional constraints

This endpoint is only available for hashed_token servers. Calling this endpoint on a token or workato_idp server returns an error.

Sample request

shell

curl  -X POST 'https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:mcp_server_handle/tokens' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": ":name"
          }'

Sample response

Returns 201 Created with the token profile at the response root rather than nested under data.

json

{
    "id": 731,
    "name": "Production token",
    "auth_type": "hashed_token",
    "created_at": "2026-07-10T10:00:00.000Z",
    "created_by": {
        "id": 42,
        "full_name": "Example User"
    },
    "token_first_symbols": "abc",
    "token_last_symbols": "wxyz",
    "plain_token": "<plain_token>"
}

PLAIN TOKEN IS SHOWN ONCE

plain_token is returned only at creation and can't be retrieved later. Store the token securely. You can use the refresh the token endpoint to generate a new token if needed.

Delete a hashed token

Deleting a hashed token doesn't remove it from the database. The hashed token profile is marked as inactive. The token immediately stops working and can no longer authenticate MCP requests.

DELETE https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:mcp_server_handle/tokens/:id

URL parameters

Name	Type	Description
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	Token profile ID.

Sample request

shell

curl  -X DELETE 'https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:mcp_server_handle/tokens/:id' \
      -H 'Authorization: Bearer <api_token>'

Sample response

Returns 200 OK with an empty response body.

This endpoint is available only for hashed_token servers. Deleted profiles no longer appear in the server's mcp_profiles array.

Refresh a hashed token

Invalidates the current token value for a profile and returns a fresh plain token.

POST https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:mcp_server_handle/tokens/:id/refresh

URL parameters

Name	Type	Description
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	Active token profile ID.

Sample request

shell

curl  -X POST 'https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:mcp_server_handle/tokens/:id/refresh' \
      -H 'Authorization: Bearer <api_token>'

Sample response

Returns 200 OK. The response has the same root-level shape as token creation and contains the plain_token, token_first_symbols, and token_last_symbols.

json

{
    "id": 731,
    "name": "Production token",
    "auth_type": "hashed_token",
    "created_at": "2026-07-10T10:00:00.000Z",
    "created_by": {
        "id": 42,
        "full_name": "Example User"
    },
    "token_first_symbols": "def",
    "token_last_symbols": "uvwx",
    "plain_token": "<new_plain_token>"
}

This endpoint is available only for hashed_token servers. The returned plain_token is exposed only in this response. Store the token securely as you can't retrieve it later.

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 https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:handle/assign_tools

URL parameters

Name	Type	Description
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
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/mcp/mcp_servers/:handle/assign_tools' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "tools": [
              {
                "trigger_application": ":trigger_application_1",
                "id": ":tool_id_1"
              },
              {
                "trigger_application": ":trigger_application_2",
                "id": ":tool_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": "hashed_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 https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:handle/assign_user_groups

URL parameters

Name	Type	Description
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_group_ids	array of strings required	IDs of the user groups to add.

Sample request

shell

curl  -X POST 'https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:handle/assign_user_groups' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "idp_user_group_ids": [":user_group_id_1", ":user_group_id_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

Removes identity provider user groups from an MCP server.

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

URL parameters

Name	Type	Description
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_group_ids	array of strings required	IDs of the user groups to remove.

Sample request

shell

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

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

Moves an MCP server to a specified folder.

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

URL parameters

Name	Type	Description
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
folder_id	number required	Target folder ID.

Sample request

shell

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

Sample response

Returns the updated MCP server object with the new folder_id reflected in created_at and updated_at timestamps.

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

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/mcp/mcp_servers/:mcp_server_handle/server_policies

URL parameters

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

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

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

URL parameters

Name	Type	Description
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/mcp/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_value },
              "quota_limits": { "per_day": :per_day_value },
              "ip_allow_list": [":ip_allow_1", ":ip_allow_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

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

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

URL parameters

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

shell

curl  -X GET 'https://YOUR_DATA_CENTER/api/mcp/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

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 https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:mcp_server_handle/tools/:id

URL parameters

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

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 https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:mcp_server_handle/tools/:id

URL parameters

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

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

shell

curl  -X GET 'https://YOUR_DATA_CENTER/api/mcp/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. Each assignment grants a single identity provider user or user group access to either all tools on the MCP 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

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

Required privilege: mcp_access_assignments.index.

GET https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:mcp_server_handle/access_assignments

URL parameters

Name	Type	Description
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/mcp/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. Set identity_type to user to include an idp_user_id string and a null idp_user_group_id for the assignment. Both identity fields are included by default.

Create an MCP access assignment

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

Required privilege: mcp_access_assignments.create.

POST https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:mcp_server_handle/access_assignments

URL parameters

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

Retrieves an access assignment belonging to an MCP server.

Required privilege: mcp_access_assignments.show.

GET https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:mcp_server_handle/access_assignments/:id

URL parameters

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

User assignments have both the idp_user_id field with the user ID and the idp_user_group_id field with a null value by default. Assignments that grant all tools have all_tools: true and tool_ids: [].

Update an MCP access assignment

Replaces the tool access scope of an existing MCP server access assignment.

Required privilege: mcp_access_assignments.update.

PUT https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:mcp_server_handle/access_assignments/:id

This path also accepts PATCH with the same replacement behavior.

URL parameters

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

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

Required privilege: mcp_access_assignments.destroy.

DELETE https://YOUR_DATA_CENTER/api/mcp/mcp_servers/:mcp_server_handle/access_assignments/:id

URL parameters

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

Developer API - MCP servers ​

Quick reference ​

List MCP servers ​

Query parameters ​

Sample request ​

Sample response ​

Create an MCP server ​

Payload ​

Sample request ​

Sample response ​

Get MCP server details ​

URL parameters ​

Sample request ​

Sample response ​

Update an MCP server ​

URL parameters ​

Payload ​

Sample request ​

Sample response ​

Delete an MCP server ​

URL parameters ​

Sample request ​

Sample response ​

Renew MCP server authentication token ​

URL parameters ​

Sample request ​

Sample response ​

MCP hashed tokens ​

Create a hashed token ​

URL parameters ​

Payload ​

Additional constraints ​

Sample request ​

Sample response ​

Delete a hashed token ​

URL parameters ​

Sample request ​

Sample response ​

Refresh a hashed token ​

URL parameters ​

Sample request ​

Sample response ​

Assign tools to an MCP server ​

URL parameters ​

Payload ​

Sample request ​

Sample response ​

Assign user groups to an MCP server ​

URL parameters ​

Payload ​

Sample request ​

Sample response ​

Remove user groups from an MCP server ​

URL parameters ​

Payload ​

Sample request ​

Sample response ​

Move MCP server to a different folder ​

URL parameters ​

Payload ​

Sample request ​

Sample response ​

Get server policy configuration ​

URL parameters ​

Sample request ​

Sample response ​

Update server policy configuration ​

URL parameters ​

Payload ​

Sample request ​

Sample response ​

List tools for an MCP server ​

URL parameters ​

Query parameters ​

Sample request ​

Sample response ​

Update tool description ​

URL parameters ​

Payload ​

Sample request ​

Developer API - MCP servers

Quick reference

List MCP servers

Query parameters

Sample request

Sample response

Create an MCP server

Payload

Sample request

Sample response

Get MCP server details

URL parameters

Sample request

Sample response

Update an MCP server

URL parameters

Payload

Sample request

Sample response

Delete an MCP server

URL parameters

Sample request

Sample response

Renew MCP server authentication token

URL parameters

Sample request

Sample response

MCP hashed tokens

Create a hashed token

URL parameters

Payload

Additional constraints

Sample request

Sample response

Delete a hashed token

URL parameters

Sample request

Sample response

Refresh a hashed token

URL parameters

Sample request

Sample response

Assign tools to an MCP server

URL parameters

Payload

Sample request

Sample response

Assign user groups to an MCP server

URL parameters

Payload

Sample request

Sample response

Remove user groups from an MCP server

URL parameters

Payload

Sample request

Sample response

Move MCP server to a different folder

URL parameters

Payload

Sample request

Sample response

Get server policy configuration

URL parameters

Sample request

Sample response

Update server policy configuration

URL parameters

Payload

Sample request

Sample response

List tools for an MCP server

URL parameters

Query parameters

Sample request

Sample response

Update tool description

URL parameters

Payload

Sample request