From cea9f36c16bbf996428e5f317da71fb0dc60fa3f Mon Sep 17 00:00:00 2001 From: Luca Chang Date: Tue, 10 Jun 2025 14:06:40 -0700 Subject: [PATCH 1/6] docs(tools): discuss tool name conflicts and how to resolve them --- docs/docs/concepts/tools.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/docs/concepts/tools.mdx b/docs/docs/concepts/tools.mdx index 53ae28ac0..0846ace2b 100644 --- a/docs/docs/concepts/tools.mdx +++ b/docs/docs/concepts/tools.mdx @@ -213,6 +213,13 @@ When implementing tools: 9. Consider rate limiting for resource-intensive operations 10. Log tool usage for debugging and monitoring +### Tool name conflicts + +MCP client applications and MCP server proxies may encounter tool name conflicts when building their own tool lists. +To resolve these conflicts, we recommend maintaining a unique identifier for each connected MCP server, and prefixing that to the tool name with `___` (three underscores) as a separator. + +For example, if two web search MCP servers called `a` and `b` both expose a `search_web` tool, client applications or proxies may consider registering these as `a___search_web` and `b___search_web` to disambiguate them. + ## Security considerations When exposing tools: From 41da03afe16b806d8143632386e82a95b553cc67 Mon Sep 17 00:00:00 2001 From: Luca Chang Date: Tue, 10 Jun 2025 15:23:51 -0700 Subject: [PATCH 2/6] docs(tools): suggest using config keys as identifiers for servers for disambiguation --- docs/docs/concepts/tools.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/concepts/tools.mdx b/docs/docs/concepts/tools.mdx index 0846ace2b..7b83d09b7 100644 --- a/docs/docs/concepts/tools.mdx +++ b/docs/docs/concepts/tools.mdx @@ -216,7 +216,7 @@ When implementing tools: ### Tool name conflicts MCP client applications and MCP server proxies may encounter tool name conflicts when building their own tool lists. -To resolve these conflicts, we recommend maintaining a unique identifier for each connected MCP server, and prefixing that to the tool name with `___` (three underscores) as a separator. +To resolve these conflicts, we recommend maintaining a unique identifier (such as a config key, in the case of client applications) for each connected MCP server, and prefixing that to the tool name with `___` (three underscores) as a separator. For example, if two web search MCP servers called `a` and `b` both expose a `search_web` tool, client applications or proxies may consider registering these as `a___search_web` and `b___search_web` to disambiguate them. From 2fb4b32026ad9bb332f09f2d05386bef1779a57c Mon Sep 17 00:00:00 2001 From: Luca Chang Date: Tue, 10 Jun 2025 15:26:41 -0700 Subject: [PATCH 3/6] docs(tools): expand on unique key for tool disambiguation --- docs/docs/concepts/tools.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/docs/concepts/tools.mdx b/docs/docs/concepts/tools.mdx index 7b83d09b7..268fc0d43 100644 --- a/docs/docs/concepts/tools.mdx +++ b/docs/docs/concepts/tools.mdx @@ -216,10 +216,12 @@ When implementing tools: ### Tool name conflicts MCP client applications and MCP server proxies may encounter tool name conflicts when building their own tool lists. -To resolve these conflicts, we recommend maintaining a unique identifier (such as a config key, in the case of client applications) for each connected MCP server, and prefixing that to the tool name with `___` (three underscores) as a separator. +To resolve these conflicts, we recommend maintaining a unique identifier for each connected MCP server, and prefixing that to the tool name with `___` (three underscores) as a separator. For example, if two web search MCP servers called `a` and `b` both expose a `search_web` tool, client applications or proxies may consider registering these as `a___search_web` and `b___search_web` to disambiguate them. +For client applications with an MCP configuration file, we recommend using the name of the server as provided by the end-user in the configuration as a unique key. Server-provided names are not guaranteed to be unique. + ## Security considerations When exposing tools: From e27aae227f67e6978f1913c1cc5cffc13df1d991 Mon Sep 17 00:00:00 2001 From: Luca Chang Date: Mon, 16 Jun 2025 11:50:04 -0700 Subject: [PATCH 4/6] Make tool name conflict docs less prescriptive --- docs/docs/concepts/tools.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/docs/concepts/tools.mdx b/docs/docs/concepts/tools.mdx index 268fc0d43..6a87d1e98 100644 --- a/docs/docs/concepts/tools.mdx +++ b/docs/docs/concepts/tools.mdx @@ -215,12 +215,14 @@ When implementing tools: ### Tool name conflicts -MCP client applications and MCP server proxies may encounter tool name conflicts when building their own tool lists. -To resolve these conflicts, we recommend maintaining a unique identifier for each connected MCP server, and prefixing that to the tool name with `___` (three underscores) as a separator. +MCP client applications and MCP server proxies may encounter tool name conflicts when building their own tool lists. For example, two connected MCP servers `web1` and `web2` may both expose a tool named `search_web`. -For example, if two web search MCP servers called `a` and `b` both expose a `search_web` tool, client applications or proxies may consider registering these as `a___search_web` and `b___search_web` to disambiguate them. +Applications most often disambiguiate tools with one of the following strategies: -For client applications with an MCP configuration file, we recommend using the name of the server as provided by the end-user in the configuration as a unique key. Server-provided names are not guaranteed to be unique. +- Concatenating a unique, user-defined server name with the tool name, e.g. `web1___search_web` and `web2___search_web`. This strategy may be preferable when unique server names are already provided by the user in a configuration file. +- Generating a random prefix for the tool name, e.g. `jrwxs___search_web` and `6cq52___search_web`. This strategy may be preferable in server proxies where user-defined unique names are not available. + +Note that the server-provided name from the initialization flow is not guaranteed to be unique and is not generally suitable for disambiguation purposes. ## Security considerations From 07b50870fe8931737475b931a8a187553534919f Mon Sep 17 00:00:00 2001 From: Luca Chang Date: Wed, 18 Jun 2025 10:24:01 -0700 Subject: [PATCH 5/6] Add URI approach to tool name conflict strategies --- docs/docs/concepts/tools.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docs/concepts/tools.mdx b/docs/docs/concepts/tools.mdx index 6a87d1e98..a03b1b9e3 100644 --- a/docs/docs/concepts/tools.mdx +++ b/docs/docs/concepts/tools.mdx @@ -221,6 +221,7 @@ Applications most often disambiguiate tools with one of the following strategies - Concatenating a unique, user-defined server name with the tool name, e.g. `web1___search_web` and `web2___search_web`. This strategy may be preferable when unique server names are already provided by the user in a configuration file. - Generating a random prefix for the tool name, e.g. `jrwxs___search_web` and `6cq52___search_web`. This strategy may be preferable in server proxies where user-defined unique names are not available. +- Using the server URI as a prefix for the tool name, e.g. `web1.example.com:search_web` and `web2.example.com:search_web`. This strategy may be suitable when working with remote MCP servers. Note that the server-provided name from the initialization flow is not guaranteed to be unique and is not generally suitable for disambiguation purposes. From 040ab9feb42caf09b33f89f90992c3f173a52b23 Mon Sep 17 00:00:00 2001 From: Luca Chang Date: Wed, 18 Jun 2025 10:32:27 -0700 Subject: [PATCH 6/6] Make tool conflict phrasing even less prescriptive --- docs/docs/concepts/tools.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/concepts/tools.mdx b/docs/docs/concepts/tools.mdx index a03b1b9e3..37506a4b4 100644 --- a/docs/docs/concepts/tools.mdx +++ b/docs/docs/concepts/tools.mdx @@ -217,7 +217,7 @@ When implementing tools: MCP client applications and MCP server proxies may encounter tool name conflicts when building their own tool lists. For example, two connected MCP servers `web1` and `web2` may both expose a tool named `search_web`. -Applications most often disambiguiate tools with one of the following strategies: +Applications may disambiguiate tools with one of the following strategies (among others; not an exhaustive list): - Concatenating a unique, user-defined server name with the tool name, e.g. `web1___search_web` and `web2___search_web`. This strategy may be preferable when unique server names are already provided by the user in a configuration file. - Generating a random prefix for the tool name, e.g. `jrwxs___search_web` and `6cq52___search_web`. This strategy may be preferable in server proxies where user-defined unique names are not available.