Preamble

Title: Namespaces
Author: Pat White ([email protected])

Abstract

As MCP servers grow in complexity and size, some mechanism for grouping tools, prompts, resources, and resource templates within a given server is needed. This could be used, for instance, to avoid duplicate tool names in a proxy server, or to present a set of tools to solve a particular scenario, like a "Draft Email" namespace in a productivity app server. A natural mechanism we've seen in programming since the early days is "Namespacing" - using a name to signify a meta grouping, and create a hierarchy to avoiding naming collisions and more. This is a proposal to introduce namespaces as a first class citizen to MCP servers.

Motivation

We have to start with a premise that LLMs are not great at picking a tool as you approach 20 tools, and outright terrible as you get to 40, and some won't even contemplate more than 40 tools for selection.

Within those boundaries, it's becoming more important to have mechanisms to narrow down the tools that are presented to LLMs by host applications for selection, and namespacing is one mechanism to use grouping to solve that problem.

In a broader sense, it's fair to say that the current MCP protocol has a bias towards smaller servers, and namespacing is one way to begin to adapt the protocol to support both smaller servers with just a default namespace, and larger servers that may have hundreds of namespaces.

Rationale

This proposal takes deep inspiration from NPM, GitHub, and other similar platforms in how to approach namespacing. The concept is a single root hierarchy (in NPM parlance that would be something like @stripe/types_v3, in github parlance that would be traego/scaled-mcp). However, there are some current limitations with LLMs which introduce a complexity, namely that "/" and "." are not accepted characters in LLM api tool names. Hence, for this proposal we'll be using a slash when the protocol allows it, and a double underscore "__" as a delimiter when slash is not an accepted character.

Specification

#334

This high level concept is relatively simple:

1. There is a new opt in capability "namespaces". If that capability is enabled, several methods are required to be exposed. The rest of this specification assume that capability has been opted in to.
2. The new methods exposed are namespace scoped list operations - <namespace>/tools/list, <namespace>/prompts/list, <namespace>/resources/list, etc. These methods behave EXACTLY like the existing capabilities but scope the results down to just the tools / resources / prompts within the namespaces
3. A new namespaces/list method is exposed which lists namespaces with descriptions
4. Tools and prompts are expected to include the namespace in the name of the item. For tools and prompts, that will be expressed as<namespace>__<tool_name>.

Backwards Compatibility

This change is fully backwards compatible and is a 100% opt in capability. A client that does not support namespaces calling into a server with namespaces will be presented with tools that have the namespace backed in (eg weather__get_city_weather) when calling the tools/list and will not have to be aware of namespaces.

Reference Implementation

https://github.com/Traego/scaled-mcp

Security Implications

None