[FEATURE] Adopt provider-prefixed tool names for all exposed MCP tools to ensure clear namespacing.

[jw408]

Feature Description

Adopt provider-prefixed tool names for all exposed MCP tools to ensure clear namespacing.

Problem Statement

When integrating multiple MCP (Model Context Protocol) servers from different providers, generic tool names can cause namespace collisions. The Glean MCP server currently registers tools with names like chat, company_search, and people_profile_search. This has proven to be problematic in both Gemini-CLI with Gemini-2.5-pro, Gemini-2.5-flash, and with claude-code (Sonnet, opus, opus 4.1)

If another registered MCP server also provides a tool named chat, it becomes ambiguous which service the agent should target. This leads to unpredictable behavior and makes it difficult for an LLM agent to reliably select the correct tool for a given task, degrading the stability of the overall system.

Additionally, while no fault of Glean, these mcp tools can be confusing to the LLM agents vs other on-disk tools.

While the current Model Context Protocol (MCP) specification does not strictly enforce a provider-prefix naming convention, it strongly recommends namespacing to ensure tool clarity and prevent collisions. The official documentation and community best practices point towards creating unique and descriptive tool names, with a URI-like structure being the suggested approach for robust namespacing.

Even the top level repo name "mcp-server" is somewhat problematic for developers consuming your repo, because it's a Glean mcp server, not a generic mcp server

Proposed Solution

To prevent these collisions, we propose prefixing all tool names with com.glean/ as according to the MCP standards recommendation. This creates a unique and explicit namespace for Glean's tools.

The current names would be changed as follows:

Current Name	Proposed Name
chat	com.glean/chat
company_search	com.glean/company_search
people_profile_search	com.glean/people_profile_search
read_documents	com.glean/read_documents

This change would make tool identification unambiguous and robust.

Alternatives Considered

One alternative is for each client to implement its own namespacing logic, wrapping the tools from each server upon registration. However, this approach is brittle and places an unnecessary burden on every consumer of the Glean MCP server. It is a standard best practice for the tool provider to ensure its tool names are reasonably unique to prevent such downstream issues.

I also considered simply hard forking the repo, but that doesn't really make sense because this package is only useful in conjunction with glean.

Additional Context

The current tool names were identified from the Glean MCP server's source code in references/mcpglean/packages/local-mcp-server/build/server.js. The file explicitly defines the following tool names:

• company_search
• people_profile_search
• chat
• read_documents

This proposal aligns with common practices in other extensible systems where plugins or providers are expected to use unique prefixes for their commands, functions, or identifiers.

Impact

Implementing this feature would significantly improve the stability and predictability of using the Glean MCP server within a multi-agent, multi-tool environment. It would eliminate a class of integration errors, reduce confusion for the LLM agent, and allow for more seamless and scalable use of Glean's capabilities alongside other MCP-compliant services.

[jw408]

Very simple patch to fix:

1 --- a/packages/local-mcp-server/src/server.ts
    2 +++ b/packages/local-mcp-server/src/server.ts
    3 @@ -24,10 +24,10 @@
    4  import { VERSION } from './common/version';
    5
    6  export const TOOL_NAMES = {
    7 -  companySearch: 'company_search',
    8 -  peopleProfileSearch: 'people_profile_search',
    9 -  chat: 'chat',
   10 -  readDocuments: 'read_documents',
   11 +  companySearch: 'com.glean/company_search',
   12 +  peopleProfileSearch: 'com.glean/people_profile_search',
   13 +  chat: 'com.glean/chat',
   14 +  readDocuments: 'com.glean/read_documents',
   15  };
   16
   17  /**

[rwjblue-glean]

What hosts have you had issues with? In my experience the hosts already namespace the provided tools based on your configured server name (e.g. if you have glean as a server in claude code, the actual tool is glean/chat).

[rwjblue-glean]

Regardless, I agree with you that we should follow the spec's guidance and have the tool names be URI like. Then we can provide a custom title so folks actually still see a nice name displayed in their host applications UI.

[jw408]

Ive run into this with both gemini-cli using Gemini-2.5-pro, and Gemini-2.5-flash, as well as claude-cli using claude Sonnet 3.7 and Opus 4.0. I do agree they show up in the display as seperate servers, but something is going wrong internal to the llm where it doesn't look at that and seems to be overly fixed on the rightmost part of the tool name.

The more closely named tools (I have one called agent_chat) there are, the more likely the llms are to get confused.

[rwjblue-glean]

Gotcha! I've already updated the tool names in our upcoming remote MCP server to follow the spec advice (went with tool names of com.glean/chat, com.glean/search, &c). Happy to land + release a PR here to follow suit if you'd like to give a PR a whirl...

[rwjblue-glean]

FWIW, Claude Desktop explicitly does not allow scoping (in the way that the spec link you shared expects). If you have an MCP tool that does not conform to [^a-zA-Z0-9_-] Claude Desktop will error when you add the server.