René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"SEP: Namespaces using URIs","articleBody":"# SEP: Namespaces using URIs\n\n## Preamble\n\n**Title:** Namespaces using URIs  \n**Author:** Tapan Chugh (@chughtapan); Huge acknowledgements to everyone from #334  \n**Type:** Standards Track  \n**Status:** Proposal  \n**Created:** 2025-08-02  \n\n## Abstract\n\nManaging 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.\n\nThis SEP provides that feature using two key contributions:\n1. Adding URIs for resources/tools in addition to prompts\n2. Adding URI-prefix based filtering to all list methods\n\nReference Implementation: https://github.com/modelcontextprotocol/python-sdk/pull/1230\n\n## Motivation\n\nThere are several key motivations for adding hierarchical addressing and filtering for MCP types:\n\n**Tool Explosion**: More tools than the model can handle (hard limits)\n- Servers exposing 100s of tools overwhelm LLM context windows\n- No standard way to organize or filter tools by purpose\n\n**Context Degradation**: Tool count within limits but causes issues anyway\n- Every tool in context reduces available tokens for actual work\n- Models struggle to select among many similar tools\n\n**Name Conflicts**: Different servers have identical names\n- Common names like `search`, `read`, `list` cause collisions\n- Current prefixing workarounds (`github_search`) don't scale\n\nPlease 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.\n\n## Specification\n\nThe specification changes are:\n\n1. 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.\n\n2. 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.\n\n### Type Changes\n\n```python\nclass Tool:\n    name: str  # from BaseMetadata\n    uri: AnyUrl  # NEW: required but auto-generated as mcp://tools/{name}\n```\n\n```python\nclass Prompt:\n    name: str  # from BaseMetadata\n    uri: AnyUrl  # NEW: required but auto-generated as mcp://prompts/{name}\n```\n\n```python\nclass Resource(BaseMetadata):\n    name: str  # from BaseMetadata\n    uri: AnyUrl  # already exists\n\n# NEW: Added validator to prevent resources using mcp://\n@model_validator(mode=\"after\")\ndef validate_uri_scheme(self) -\u003e \"Resource\":\n    # Prevent resources from using mcp://\n```\n\n### Request Changes\n\n```python\n# Before\nclass PaginatedRequestParams(RequestParams):\n    cursor: Cursor | None = None\n\nclass PaginatedRequest(Request[PaginatedRequestParams | None, MethodT])\nclass PaginatedResult(Result)\n```\n\n```python\n# After\nclass ListFilters(BaseModel):\n    uri_paths: list[AnyUrl] | None = None  # Filter by multiple URI prefixes\n\nclass ListRequestParams(RequestParams):\n    filters: ListFilters | None = None\n    cursor: Cursor | None = None\n```\n\nThis enables queries like:\n- List all math tools: `filters: { uri_paths: [\"mcp://tools/math/\"] }`\n- List multiple groups: `filters: { uri_paths: [\"mcp://tools/math/\", \"mcp://tools/string/\"] }`\n\nAll list requests now support prefix filtering:\n- `ListResourcesRequest`\n- `ListToolsRequest`\n- `ListPromptsRequest`\n- `ListResourceTemplatesRequest`\n\n### Group Discovery\n\nThis SEP proposes the use of standard URIs for discovering available groups:\n\n```\nmcp://groups/tools      # Returns available tool groups\nmcp://groups/prompts    # Returns available prompt groups\nmcp://groups/resources  # Returns available resource groups\n```\n\nThese URIs can be further organized into directories/pages as server requirements scale.\n\n## Rationale\n\n- 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.\n- 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.\n- This SEP does not dictate how LLMs should discover tools automatically. While hierarchies are helpful, #322 and the broader search tools discussion is more appropriate there.\n\n### Design Decisions\n\n1. **URI Scheme**: Using `mcp://` prevents conflicts with HTTP/file URLs\n2. **Auto-generation**: Tools and prompts get automatic URIs from names for backward compatibility\n3. **Resources require explicit URIs**: Prevents accidental namespace pollution\n4. **Multiple path filters**: More flexible than single prefix, enables cross-group queries\n5. **Backward compatible**: Name-based lookups continue to work\n\n### Design Alternatives\n\nWhile adding URI fields directly into Tool and Prompt classes leads to some duplication:\n1. 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.\n2. 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.\n\n### Comparison with Issue #1300 (Groups and Tags)\n\n[Issue #1300](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1300) proposes a different approach to the same problem:\n\n| **Aspect** | **This Proposal (URIs)** | **Issue #1300 (Groups/Tags)** |\n|------------|--------------------------|------------------------------|\n| Approach | Hierarchical URIs | Flat groups + tags |\n| Scalability | Arbitrary hierarchy depth | Two-level hierarchy (groups / tools) |\n| Filtering | URI path prefixes | Group/tag membership |\n| Conflicts | Prevented by URI uniqueness | Still possible within groups |\n\nKey differences:\n- **Hierarchical vs Flat**: URIs provide unlimited hierarchy; groups/tags are essentially flat\n- **Consistency**: URIs unify tools, prompts, and resources; groups/tags only proposed for tools\n- **Identity vs Metadata**: URIs are part of identity; groups/tags are separate metadata.\n\nTags are complementary to URIs filters and could provide cross-cutting concerns (e.g., `#experimental`, `#deprecated`).\n\n### Prior Art and References\n\n- **DNS/Internet Naming**: Hierarchical system that enabled internet scale\n- **REST API Design**: Hierarchical paths for intuitive navigation\n- **Kubernetes**: API groups and namespaces organize resources\n\n\n## Backward Compatibility\n\nThese 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.\n\n## Reference Implementation\n\n**Python SDK**: https://github.com/modelcontextprotocol/python-sdk/pull/1230\n- Complete implementation with tests\n- Hierarchical organization example\n- URI validation and filtering\n\n**TypeScript SDK**: Implementation in progress\n\n## Example Usage\n\n### Server Implementation\n\n```python\n@mcp.tool(uri=\"mcp://tools/math/add\")\ndef add(a: float, b: float) -\u003e float:\n    \"\"\"Add two numbers.\"\"\"\n    return a + b\n\n@mcp.tool(uri=\"mcp://tools/string/reverse\")\ndef reverse(text: str) -\u003e str:\n    \"\"\"Reverse a string.\"\"\"\n    return text[::-1]\n```\n\n### Group Discovery Resource\n\n```python\n@mcp.resource(\"mcp://groups/tools\")\ndef get_tool_groups() -\u003e str:\n    return json.dumps({\n        \"groups\": [\n            {\"name\": \"math\", \"uri_paths\": [\"mcp://tools/math/\"]},\n            {\"name\": \"string\", \"uri_paths\": [\"mcp://tools/string/\"]}\n        ]\n    })\n```\n\n### Client Usage\n\n```python\n# List math tools only\ntools = await client.list_tools(\n    filters={\"uri_paths\": [\"mcp://tools/math/\"]}\n)\n\n# Call by name (backward compatible)\nresult = await client.call_tool(\"add\", {\"a\": 5, \"b\": 3})\n\n# Call by URI (explicit namespace)\nresult = await client.call_tool(\"mcp://tools/math/add\", {\"a\": 5, \"b\": 3})\n```\n\n## Security Implications\n\nNone identified. The `mcp://` scheme will be reserved for protocol use, preventing confusion for users.\n\n## Future Extensions\n\nThis URI foundation enables:\n- **Versioning**: `mcp://tools/math/add/v2`\n- **Permissions**: ACLs based on URI paths\n- **Federation**: Cross-server references\n- **Additional Filters**: Orthogonal categorization","author":{"url":"https://github.com/chughtapan","@type":"Person","name":"chughtapan"},"datePublished":"2025-08-03T00:57:43.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":6},"url":"https://github.com/1292/modelcontextprotocol/issues/1292"}