(feat): make the root URL the primary MCP endpoint

[ChiragAgg5k]

Problem

The hosted Appwrite MCP server is currently configured and documented at https://mcp.appwrite.io/mcp. We want the shorter origin URL, https://mcp.appwrite.io/, to be the primary endpoint while still supporting the conventional /mcp path.

Change

• Serve the same Streamable HTTP MCP handler directly at both / and /mcp without redirects.
• Advertise path-matching RFC 9728 protected-resource metadata for each URL.
• Accept access tokens audience-bound to either resource URI while preserving issuer and project validation.
• Make the root URL the default in every client setup example and in MCP Registry metadata.
• Update the authentication documentation and regenerate the OAuth flow diagram.

OAuth behavior

The root and /mcp URLs each return a 401 challenge pointing to metadata whose resource exactly matches the requested endpoint:

• / → /.well-known/oauth-protected-resource
• /mcp → /.well-known/oauth-protected-resource/mcp

Both resource audiences identify the same hosted service and are accepted by the shared token verifier.

Verification

• Ruff passes.
• Black check passes.
• Pyright passes with no errors or warnings.
• All 169 unit tests pass.
• Docker image builds successfully.
• Generated PNG was visually verified against its SVG source.

[greptile-apps]

Greptile Summary

This PR promotes https://mcp.appwrite.io/ to the primary MCP endpoint while preserving /mcp as a fully functional alias — both serve identical Streamable HTTP traffic, each with their own path-matching RFC 9728 protected-resource metadata, and the shared token verifier now accepts audiences bound to either resource URI.

• canonical_resource() is updated to return the root URL (public_base_url() + "/"), mcp_path_resource() is introduced for the /mcp alias, and _accepted_resource() replaces _audience_ok() to return whichever accepted audience the token is bound to — enabling backward-compatible token reuse across both endpoints.
• In http_app.py, a new / route and a dedicated mcp_path_protected_resource_metadata_endpoint are added; RequireBearer now reads scope["path"] to select the matching resource URI for the 401 challenge, keeping WWW-Authenticate metadata URLs path-accurate per RFC 9728.
• All client setup examples in the docs and server.template.json are updated to the shorter root URL, with the /mcp alias noted as still supported.

Confidence Score: 5/5

Safe to merge — the changes are self-consistent, backward-compatible, and well-tested.

Both the auth and HTTP layers are updated together coherently: the new root endpoint, the alias, the dual-audience token acceptance, and the path-scoped 401 challenges all line up. Route ordering in Starlette correctly places specific well-known paths before the catch-all / route so none of the metadata endpoints are shadowed. Existing tokens issued against the /mcp audience continue to work at both endpoints. The 169-test suite has been extended with new cases for each added behavior, and all critical edge cases (path-based resource selection, per-endpoint metadata, cross-audience acceptance) are covered.

No files require special attention.

Important Files Changed

Filename	Overview
src/mcp_server_appwrite/auth.py	Refactors canonical_resource() to return the root URL, adds mcp_path_resource() as an alias, and updates _accepted_resource() to accept tokens bound to either audience. Logic is correct and consistent.
src/mcp_server_appwrite/http_app.py	Adds "/" as the primary MCP route alongside the "/mcp" alias, splits the well-known metadata endpoint into two separate handlers, and correctly routes 401 challenges to path-matching resource metadata. Route ordering is correct (specific routes precede "/").
tests/unit/test_auth.py	Updated tests cover both canonical_resource() and mcp_path_resource() URL values, both audience-matching paths, and the renamed _accepted_resource() API. Coverage is thorough.
tests/unit/test_http_app.py	New RequireBearerTests class validates path-based resource selection in 401 challenges; metadata endpoint tests verify each well-known URL advertises its matching resource. Route coverage assertions are updated for both "/" and "/mcp".
server.template.json	MCP Registry remote URL updated to root endpoint.
README.md	All client configuration examples updated to use the root URL, with the /mcp alias mentioned as still supported.
docs/authentication.md	OAuth flow diagram updated to show "/" as the primary endpoint; description of /mcp alias and dual token audience acceptance added.

_{Reviews (1): Last reviewed commit: "(feat): make the root URL the primary MC..." | Re-trigger Greptile}