SEP: Namespaces using URIs

Preamble

Title: Namespaces using URIs
Author: Tapan Chugh (@chughtapan); Huge acknowledgements to everyone from #334
Type: Standards Track
Status: Proposal
Created: 2025-08-02

Abstract

Managing a large number of tools and resources at scale is a problem that several in the MCP community have recently experienced and attempted to mitigate. While the namespaces proposal (#334) attempted to solve the problem, the maintainers' recommendation was that URIs are better suited for hierarchical aggregation.

This SEP provides that feature using two key contributions:

1. Adding URIs for resources/tools in addition to prompts
2. Adding URI-prefix based filtering to all list methods

Reference Implementation: modelcontextprotocol/python-sdk#1230

Motivation

There are several key motivations for adding hierarchical addressing and filtering for MCP types:

Tool Explosion: More tools than the model can handle (hard limits)

• Servers exposing 100s of tools overwhelm LLM context windows
• No standard way to organize or filter tools by purpose

Context Degradation: Tool count within limits but causes issues anyway

• Every tool in context reduces available tokens for actual work
• Models struggle to select among many similar tools

Name Conflicts: Different servers have identical names

• Common names like search, read, list cause collisions
• Current prefixing workarounds (github_search) don't scale

Please see #334 for a more detailed discussion. There are also several related questions and proposals from the community (see: #1280, #1275, #204, #1279) and several others. The original namespaces proposal was rejected with a recommendation that URIs are the preferred approach for handling hierarchies. This SEP offers that implementation.

Specification

The specification changes are:

1. All MCP server capabilities (resources, tools, prompts) have URI fields. The mcp:// prefix is reserved for the protocol's internal usage and cannot be used by resources. URIs are optional for tools and prompts but will be auto-generated.

2. URI-prefix based filtering is added as an optional capability for all list methods (list_tools, list_resources, etc.) in addition to existing pagination implementation.

Type Changes

class Tool:
    name: str  # from BaseMetadata
    uri: AnyUrl  # NEW: required but auto-generated as mcp://tools/{name}

class Prompt:
    name: str  # from BaseMetadata
    uri: AnyUrl  # NEW: required but auto-generated as mcp://prompts/{name}

class Resource(BaseMetadata):
    name: str  # from BaseMetadata
    uri: AnyUrl  # already exists

# NEW: Added validator to prevent resources using mcp://
@model_validator(mode="after")
def validate_uri_scheme(self) -> "Resource":
    # Prevent resources from using mcp://

Request Changes

# Before
class PaginatedRequestParams(RequestParams):
    cursor: Cursor | None = None

class PaginatedRequest(Request[PaginatedRequestParams | None, MethodT])
class PaginatedResult(Result)

# After
class ListFilters(BaseModel):
    uri_paths: list[AnyUrl] | None = None  # Filter by multiple URI prefixes

class ListRequestParams(RequestParams):
    filters: ListFilters | None = None
    cursor: Cursor | None = None

This enables queries like:

• List all math tools: filters: { uri_paths: ["mcp://tools/math/"] }
• List multiple groups: filters: { uri_paths: ["mcp://tools/math/", "mcp://tools/string/"] }

All list requests now support prefix filtering:

• ListResourcesRequest
• ListToolsRequest
• ListPromptsRequest
• ListResourceTemplatesRequest

Group Discovery

This SEP proposes the use of standard URIs for discovering available groups:

mcp://groups/tools      # Returns available tool groups
mcp://groups/prompts    # Returns available prompt groups
mcp://groups/resources  # Returns available resource groups

These URIs can be further organized into directories/pages as server requirements scale.

Rationale

• The choice of URIs for tools and prompts is pragmatic: it allows clients and users to only learn and navigate a single type of hierarchy, and not add additional overhead with new concepts.
• For dealing with challenges like tool name clashes (e.g., adding proxies) URIs solve the issue trivially. For dealing with scale, hierarchical aggregation and filtering presents an initial choice. Other concepts (e.g., groups, toolsets) are implementable on top of this and helpful for deterministic search.
• This SEP does not dictate how LLMs should discover tools automatically. While hierarchies are helpful, [RFC] Search #322 and the broader search tools discussion is more appropriate there.

Design Decisions

1. URI Scheme: Using mcp:// prevents conflicts with HTTP/file URLs
2. Auto-generation: Tools and prompts get automatic URIs from names for backward compatibility
3. Resources require explicit URIs: Prevents accidental namespace pollution
4. Multiple path filters: More flexible than single prefix, enables cross-group queries
5. Backward compatible: Name-based lookups continue to work

Design Alternatives

While adding URI fields directly into Tool and Prompt classes leads to some duplication:

1. Moving URIs directly into BaseMetadata would require making URIs optional, since other classes also inherit from BaseMetadata. Current choice keeps it required at the protocol layer.
2. Creating a new base class with URI just for the target classes might be better in the long term for adding new capabilities, but not considered to keep this SEP more contained.

Comparison with Issue #1300 (Groups and Tags)

Issue #1300 proposes a different approach to the same problem:

Key differences:

• Hierarchical vs Flat: URIs provide unlimited hierarchy; groups/tags are essentially flat
• Consistency: URIs unify tools, prompts, and resources; groups/tags only proposed for tools
• Identity vs Metadata: URIs are part of identity; groups/tags are separate metadata.

Tags are complementary to URIs filters and could provide cross-cutting concerns (e.g., #experimental, #deprecated).

Prior Art and References

• DNS/Internet Naming: Hierarchical system that enabled internet scale
• REST API Design: Hierarchical paths for intuitive navigation
• Kubernetes: API groups and namespaces organize resources

Backward Compatibility

These changes are fully backward compatible for client code. Although URIs for prompts and tools are now required, SDKs can automatically generate these using names. Existing name-based lookups continue to work without changes.

Reference Implementation

Python SDK: modelcontextprotocol/python-sdk#1230

• Complete implementation with tests
• Hierarchical organization example
• URI validation and filtering

TypeScript SDK: Implementation in progress

Example Usage

Server Implementation

@mcp.tool(uri="mcp://tools/math/add")
def add(a: float, b: float) -> float:
    """Add two numbers."""
    return a + b

@mcp.tool(uri="mcp://tools/string/reverse")
def reverse(text: str) -> str:
    """Reverse a string."""
    return text[::-1]

Group Discovery Resource

@mcp.resource("mcp://groups/tools")
def get_tool_groups() -> str:
    return json.dumps({
        "groups": [
            {"name": "math", "uri_paths": ["mcp://tools/math/"]},
            {"name": "string", "uri_paths": ["mcp://tools/string/"]}
        ]
    })

Client Usage

# List math tools only
tools = await client.list_tools(
    filters={"uri_paths": ["mcp://tools/math/"]}
)

# Call by name (backward compatible)
result = await client.call_tool("add", {"a": 5, "b": 3})

# Call by URI (explicit namespace)
result = await client.call_tool("mcp://tools/math/add", {"a": 5, "b": 3})

Security Implications

None identified. The mcp:// scheme will be reserved for protocol use, preventing confusion for users.

Future Extensions

This URI foundation enables:

• Versioning: mcp://tools/math/add/v2
• Permissions: ACLs based on URI paths
• Federation: Cross-server references
• Additional Filters: Orthogonal categorization