---
schema_version: "1"
id: 9948d73e0ffed2168bcb9b595cb7e3cdd0fc532cc5e6b7467095f79c5536a152
title: MCP Tool Mapping Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/latest/policies-included-mcp-tool-mapping.md
canonical_url: https://docs.mulesoft.com/gateway/latest/policies-included-mcp-tool-mapping
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 76d706ba09de8065afb798233b7fe4bc58aceb0795e7c6946ed3df60f825246d
description: MuleSoft Documentation Site
release: "1.14"
latest: true
---
---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, mcp, tool mapping
---

# MCP Tool Mapping Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Tool Mapping</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Redefines tool names and descriptions to reduce prompt complexity and improve LLM comprehension</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.11.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-tool-mapping-release-notes">MCP Tool Mapping</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Tool Mapping policy intercepts MCP protocol traffic and applies configurable name
transformations to tools.

With this policy, you can:

- Rename tools for readability

- Rename tools for consistency across different MCP servers

- Add prefixes or suffixes to tool names for namespacing

- Create pattern-based transformations by using regex

- Create custom descriptions for mapped tools

The MCP Tool Mapping policy supports both outbound mapping (transforming tool names in `tools/list`
responses from backend to client) and inbound mapping (reverse-transforming tool names in
`tools/call` requests from client to backend). The policy automatically maintains bidirectional
mapping, ensuring that tool names are correctly transformed in both directions to maintain
consistency between client and backend.

The policy works with both MCP transport types:

- Standard JSON over HTTP: Transforms tool names in JSON-RPC messages

- Server-Sent Events (SSE): Transforms tool names in SSE streaming responses

## Configuring Policy Parameters

### Omni Gateway Local Mode

The MCP Tool Mapping policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Tool Name Mappings</p></div></div></td><td><div><div><p>Defines the tool name mappings. Each mapping specifies how to transform tool names between the client and backend.</p></div></div></td></tr><tr><td><div><div><p>Source Tool Name</p></div></div></td><td><div><div><p>Defines the original tool name from the MCP server or a regex pattern for pattern-based matching with capture group replacement.</p></div></div></td></tr><tr><td><div><div><p>Mapped Tool Name</p></div></div></td><td><div><div><p>Defines the new tool name to use in responses. For regex mappings, use <code>$1</code>, <code>$2</code>, <code>$3</code>, and so on to reference capture groups.</p></div></div></td></tr><tr><td><div><div><p>Mapped Tool Description</p></div></div></td><td><div><div><p>Optional new description for the tool. If not specified, the original description is used. New descriptions aren’t supported for regex mappings.</p></div></div></td></tr><tr><td><div><div><p>Mapping Type</p></div></div></td><td><div><div><p>Determines how the tool mapping is processed. Supported values are <strong>Literal</strong> for exact string matching and <strong>Regex</strong> for pattern matching with capture groups.</p></div></div></td></tr><tr><td><div><div><p>Log Mappings</p></div></div></td><td><div><div><p>Logs tool names and mappings for debugging if enabled. For example:</p></div><div><div><pre>Mapped outbound tool (literal): get_me -&gt; ss_get_me
Passthrough outbound tool (no mapping): get_release_by_tag</pre></div></div></div></td></tr></tbody></table>

## Mapping Types

The MCP Tool Mapping policy supports literal mapping for exact string matching and regex mapping for
pattern-based matching with capture group replacement.

### Literal Mapping

Literal mappings perform exact string matching for specific tool names. For example, given the
following parameters:

- **Source Tool Name**: `get_weather`

- **Mapped Tool Name**: `weather_lookup`

- **Mapped Tool Description**: `Get current weather conditions`

- **Mapping Type**: **Literal**

The policy transforms the tool name in the `tools/list` response and `tools/call` request:

- `tools/list` response: `get_weather` to `weather_lookup`

- `tools/call` request: `weather_lookup` to `get_weather` (automatic reverse mapping)

### Regex Mapping

Regex mappings use pattern-based matching with capture group replacement. For example, given the
following parameters:

- **Source Tool Name**: `get_(.+)`

- **Mapped Tool Name**: `fetch_$1`

- **Mapping Type**: **Regex**

The policy transforms the tool name in the `tools/list` response:

- `get_weather` to `fetch_weather`

- `get_user` to `fetch_user`

- `delete_item` remains unchanged (doesn’t match pattern)

## Bidirectional Mapping

For outbound `tools/list` mapping response, the policy transforms tool names when the backend MCP
server returns a list of available tools:

1.  Backend MCP server returns tools: `["get_weather", "get_user", "delete_item"]`

2.  Policy applies mappings:

    - `get_weather` to `weather_lookup` (literal match)

    - `get_user` to `user_info` (literal match)

    - `delete_item` remains unchanged (no mapping)

3.  Client receives: `["weather_lookup", "user_info", "delete_item"]`

For inbound `tools/call` mapping requests, the policy transforms tool names when the client calls a
tool:

The policy reverse-transforms tool names when the client calls a tool:

1.  Client calls: `weather_lookup` (the mapped name)

2.  Policy reverse-maps: `weather_lookup` to `get_weather`

3.  Backend receives: `get_weather` (original name)

## Namespace Isolation Use Case

Add prefixes to avoid tool name conflicts between multiple MCP servers. For example, this
configuration adds the prefix `server1_` to all tool names:

- **Source Tool Name**: `(.+)`

- **Mapped Tool Name**: `server1_$1`

- **Mapping Type**: `regex`

## Consistent Naming Use Case

Standardize tool names across different servers. For example, this configuration standardizes the
name of `fetch` and `retrieve` functions from different servers to `get` functions:

- Mapping 1:

  - **Source Tool Name**: `fetchWeather`

  - **Mapped Tool Name**: `get_weather`

  - **Mapping Type**: `literal`

- Mapping 2:

  - **Source Tool Name**: `retrieveUser`

  - **Mapped Tool Name**: `get_user`

  - **Mapping Type**: `literal`

## See Also

- [MCP Access Control: How the Policies Work Together](https://docs.mulesoft.com/gateway/latest/policies-mcp-access-control-together)

- [MCP Global Access](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-global-access)

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control)

- [Included Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)