Tool and prompt aliases for MCP server portals

src/content/changelog/access/2026-05-12-mcp-portal-tool-prompt-aliases.mdx

@@ -0,0 +1,26 @@
+---
+title: Tool and prompt aliases for MCP server portals
+description: Rename tools and prompts and edit their descriptions on MCP server portals without modifying the upstream server.
+date: 2026-05-12
+products:
+  - access
+---
+
+Many organizations connect third-party MCP servers through [MCP server portals](/cloudflare-one/access-controls/ai-controls/mcp-portals/), such as those provided by SaaS vendors. These organizations have no control over how the server author named tools or wrote descriptions. Unclear names and missing descriptions make it harder for AI agents to select the right tool and harder for users to understand what is available to them.
+
+Administrators can now [rename tools and prompts](/cloudflare-one/access-controls/ai-controls/mcp-portals/#tool-and-prompt-aliases) and rewrite their descriptions directly on the portal, without modifying the upstream MCP server. For example, a vague tool named `super_cool_tool` can become `search_customer_records` with a description tailored to your organization.
+
+![Edit tool modal showing Name and Description fields for an MCP server tool](~/assets/images/changelog/access/portal-edit-tool-modal.png)
+
+Modified tools display a **Modified** label in the tools list so administrators can see which tools have been customized at a glance.
+
+![Tools authorized list showing a Modified label on a renamed tool](~/assets/images/changelog/access/portal-tools-authorized-modified.png)
+
+Aliases override the metadata that MCP clients receive when they connect to the portal. You can set them at two levels:
+
+- **Per portal**: Applies only within a specific portal. Takes precedence over server-level aliases.
+- **Per server**: Applies across all portals that use the server.
+
+You can reset an alias at any time to restore the original upstream name.
+
+For more information, refer to [Tool and prompt aliases](/cloudflare-one/access-controls/ai-controls/mcp-portals/#tool-and-prompt-aliases).

src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx

@@ -27,6 +27,8 @@ MCP server portals provide the following capabilities:
 
 - **Customized tools per portal**: Admins can tailor an MCP portal to a particular use case by choosing the specific tools and prompt templates that they want to make available to users through the portal. This allows users to access a curated set of tools and prompts — the less external context exposed to the AI model, the better the AI responses tend to be.
 
+- **Tool and prompt aliases**: Admins can [rename tools and prompts](#tool-and-prompt-aliases) and edit their descriptions at the portal or server level without modifying the upstream MCP server. Aliases improve tool discoverability for end users and help AI agents make better tool selection decisions.
+
 - **Context optimization**: Portals support query parameter options that reduce context window usage by minimizing or hiding tool definitions. Refer to [Optimize context](#optimize-context) for details.
 
 - **Non-browser client support**: MCP clients authenticate to the portal using a standard OAuth 2.0 authorization code flow via [managed OAuth](/cloudflare-one/access-controls/applications/http-apps/managed-oauth/). Non-browser clients receive a `401` response with a `WWW-Authenticate` header pointing to Access's OAuth discovery endpoints, rather than a browser redirect.
@@ -128,6 +130,108 @@ Cloudflare Access automatically creates an Access application for each MCP serve
    2. <Render file="access/access-block-page" product="cloudflare-one" />
 5. Select **Save**.
 
+## Tool and prompt aliases
+
+Tool and prompt names are defined by the upstream MCP server and cannot be changed through the MCP protocol itself. Aliases let administrators override these names and descriptions at the portal or server level so MCP clients receive metadata that better fits your organization.
+
+Use aliases to:
+
+- Replace unclear tool names with descriptive names that reflect your organization's terminology.
+- Add or improve descriptions so AI agents select the correct tool more often.
+- Standardize naming conventions across multiple MCP servers in a portal.
+
+Alias names can be up to 40 characters long and must match `^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$`. For example, `search_customer_records` or `get-user-profile`. No two tools or prompts on the same server can have the same name, whether that name is an alias or the original upstream name.
+
+### Alias precedence
+
+Aliases can be set at the portal level or the server level. When both exist for the same tool or prompt, the portal-level alias takes precedence.
+
+| Level | Scope | Where to configure |
+| ----- | ----- | ------------------ |
+| Portal | Applies only within a specific portal | Edit the portal in **AI controls** > **MCP server portals** |
+| Server | Applies across all portals that use the server | Edit the server in **AI controls** > **MCP servers** |
+
+If no alias is set, the portal uses the original name and description from the upstream MCP server.
+
+### Set aliases in the dashboard
+
+<Tabs syncKey="aliasLevel"> <TabItem label="Portal-level alias">
+
+To set an alias that applies to a specific portal:
+
+1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **AI controls**.
+2. Find the portal you want to configure, then select the three dots > **Edit**.
+3. Go to the **Servers** tab.
+4. In the servers table, select the **Tools authorized** or **Prompts authorized** value for the server you want to configure. This value appears as a fraction, for example `10/10`, showing how many are enabled.
+5. Find the tool or prompt you want to modify, then select the three dots > **Edit**.
+6. In the modal, update the **Name** and **Description** as needed.
+7. Select **Confirm**.
+
+</TabItem> <TabItem label="Server-level alias">
+
+To set an alias that applies across all portals using a server:
+
+1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **AI controls**.
+2. Go to the **MCP servers** tab.
+3. Find the server you want to configure, then select the three dots > **Edit**.
+4. Go to the **Tools** or **Prompts** tab.
+5. Find the tool or prompt you want to modify, then select the three dots > **Edit**.
+6. In the modal, update the **Name** and **Description** as needed.
+7. Select **Confirm**.
+8. Scroll to the bottom of the page and select **Save server**.
+
+</TabItem> </Tabs>
+
+Tools and prompts that have been modified display a **Modified** label in the dashboard.
+
+### Set aliases with the API
+
+To set aliases, send a `PUT` request to the [Update a MCP Portal](/api/resources/zero_trust/subresources/access/subresources/ai_controls/subresources/mcp/subresources/portals/methods/update/) endpoint. Include the `alias` field in `updated_tools` or `updated_prompts` for each tool or prompt you want to rename.
+
+<APIRequest
+	path="/accounts/{account_id}/access/ai-controls/mcp/portals/{id}"
+	method="PUT"
+	json={{
+		servers: [
+			{
+				server_id: "example-server",
+				updated_tools: [
+					{
+						name: "original_tool_name",
+						enabled: true,
+						description: "A clearer description of what this tool does.",
+						alias: "renamed_tool",
+					},
+				],
+				updated_prompts: [
+					{
+						name: "original_prompt_name",
+						enabled: true,
+						description: "An updated description for this prompt.",
+						alias: "renamed_prompt",
+					},
+				],
+			},
+		],
+	}}
+/>
+
+To set server-level aliases that apply across all portals, send a `PUT` request to the [Update a MCP Server](/api/resources/zero_trust/subresources/access/subresources/ai_controls/subresources/mcp/subresources/servers/methods/update/) endpoint with the same `updated_tools` and `updated_prompts` fields.
+
+### Reset an alias
+
+To reset a tool or prompt to its original upstream name, open the edit modal for the tool or prompt in the dashboard and clear the modified name and description. When using the API, omit the `alias` field from the corresponding entry in `updated_tools` or `updated_prompts`.
+
+### How aliases affect end users
+
+When an administrator sets an alias, connected MCP clients receive the aliased name and description instead of the original. End users do not see the original name; the alias is transparent.
+
+If an administrator changes an alias while a user has an active session, the user must reauthenticate to the portal to receive the update. Refer to [Manage portal sessions](#manage-portal-sessions) for reauthentication options.
+
+:::caution
+If the upstream MCP server renames a tool or prompt, any alias you set for that tool or prompt will be removed after the next sync. The tool or prompt will appear under its new upstream name. After a sync, verify that your aliases still apply.
+:::
+
 ## Code mode
 
 [Code mode](/agents/api-reference/codemode/) is turned on by default on all MCP server portals. It reduces context window usage by collapsing all tools in the portal into a single `code` tool. Instead of loading a separate tool definition for each upstream MCP server tool, the connected AI agent writes JavaScript that calls typed `codemode.*` methods. The generated code runs in an isolated [Dynamic Worker](/workers/runtime-apis/bindings/worker-loader/) environment, which keeps authentication credentials and environment variables out of the model context.