docs+tests: cover RFC 7591 dynamic client registration

The cloud OAuth server now advertises an open registration_endpoint
(RFC 7591), so MCP clients self-register without pre-shared credentials.
This server is the OAuth 2.1 Resource Server and needs no runtime change;
document the now-live self-service registration step and lock the
discovery contract it depends on.

- README: explicit self-service DCR step (public/PKCE, no client_id/secret
  to provision), project-setup note, and regional APPWRITE_ENDPOINT caveat
  (token iss is validated against it).
- unit: supported_scopes works against DCR-enabled discovery (no network).
- integration: assert the AS advertises registration_endpoint == issuer/register
  and exposes scopes_supported; skips when the endpoint predates DCR.

Author: ChiragAgg5k

README.md

@@ -46,13 +46,16 @@ The MCP server validates the bearer access token on every request and forwards i
 
 1. The client requests `/<project_id>/mcp` without a token and receives `401` with a `WWW-Authenticate` header pointing to the protected-resource metadata.
 2. The client fetches `GET /.well-known/oauth-protected-resource/<project_id>/mcp` (RFC 9728), which lists the project's authorization server (`<APPWRITE_ENDPOINT>/oauth2/<project_id>`) and supported scopes.
-3. The client discovers the authorization server (RFC 8414 / OIDC), registers (RFC 7591), and runs the OAuth 2.1 + PKCE authorization-code flow, including the RFC 8707 `resource` parameter that binds the token's audience to this server.
-4. The client calls `/<project_id>/mcp` with `Authorization: Bearer <token>`.
+3. The client discovers the authorization server (RFC 8414 / OIDC) and **self-registers** via RFC 7591 Dynamic Client Registration — the project's OAuth server exposes an open `registration_endpoint`, so there is no client ID or secret to pre-provision. MCP clients register as public (PKCE) clients automatically.
+4. The client runs the OAuth 2.1 + PKCE authorization-code flow, including the RFC 8707 `resource` parameter that binds the token's audience to this server.
+5. The client calls `/<project_id>/mcp` with `Authorization: Bearer <token>`.
 
 ## Project setup
 
 Each project must enable its OAuth server (`oAuth2Server.enabled = true`) and include the scopes the MCP advertises in `oAuth2Server.scopes`. The advertised set covers read+write for users, sessions, teams, databases (tables/columns/indexes/rows), storage (buckets/files), functions (executions), messaging (providers/topics/subscribers/targets/messages), and sites, plus `locale.read` and `avatars.read`. Clients request only the subset they need; the consent screen and the API's per-route scope checks enforce what is actually granted.
 
+No OAuth client needs to be created by hand: enabling the OAuth server also exposes the RFC 7591 `registration_endpoint`, and MCP clients self-register against it on first connect. Each registered client becomes an `apps` document in the project.
+
 ## Tool surface
 
 The server starts in a compact workflow so the MCP client only sees a small operator-style surface while the full Appwrite catalog stays internal.
@@ -69,6 +72,8 @@ The server starts in a compact workflow so the MCP client only sees a small oper
 
 The server is a standard ASGI app. Configure it via environment variables (see [`.env.example`](.env.example)) — chiefly `APPWRITE_ENDPOINT` (the Appwrite Cloud base) and `MCP_PUBLIC_URL` (the external URL clients use to reach this server, used to build canonical resource URIs and metadata). `GET /healthz` is a liveness probe.
 
+> **Regional endpoints:** `APPWRITE_ENDPOINT` must be the host that actually **issues** tokens. The server validates each token's `iss` claim against this endpoint, so if your project lives in a region whose discovery reports a regional issuer (e.g. `https://fra.cloud.appwrite.io/v1`), set `APPWRITE_ENDPOINT` to that regional host — otherwise valid tokens are rejected.
+
 ### Docker (recommended)
 
 ```bash

tests/integration/test_oauth_discovery.py

@@ -0,0 +1,68 @@
+"""Live contract test for the OAuth authorization-server discovery the MCP relies on.
+
+The hosted MCP server is an OAuth 2.1 Resource Server: it points clients at the
+project's Appwrite authorization server, and MCP-aware clients then self-register
+via RFC 7591 Dynamic Client Registration. That registration step only works if the
+authorization server advertises ``registration_endpoint`` in its discovery document
+(added by the cloud ``feat/oauth2-dynamic-client-registration`` work).
+
+This test locks that contract end-to-end against the configured Appwrite endpoint:
+the same discovery document the MCP fetches for ``scopes_supported`` must advertise
+the registration endpoint the README promises. It is skipped without live config.
+
+Note: it asserts against the document's own ``issuer`` (not the request host) so it
+is correct even when the endpoint regionally redirects (e.g. ``fra.cloud.appwrite.io``).
+"""
+
+from __future__ import annotations
+
+import os
+import unittest
+
+import httpx
+
+from mcp_server_appwrite import auth
+
+from .support import requires_live_integration
+
+
+@requires_live_integration
+class OAuthDiscoveryContractTests(unittest.TestCase):
+    def _discovery(self) -> dict:
+        project_id = os.environ["APPWRITE_PROJECT_ID"]
+        url = f"{auth.issuer_url(project_id)}/.well-known/openid-configuration"
+        resp = httpx.get(url, timeout=10.0, follow_redirects=True)
+        resp.raise_for_status()
+        return resp.json()
+
+    def test_discovery_advertises_dynamic_client_registration(self):
+        doc = self._discovery()
+
+        # The fields the OAuth 2.1 + DCR client flow depends on.
+        issuer = doc.get("issuer")
+        self.assertTrue(issuer, "discovery document missing issuer")
+        self.assertTrue(doc.get("token_endpoint"), "discovery missing token_endpoint")
+
+        # RFC 7591: registration must be advertised for clients to self-register.
+        # Skip (rather than fail) when the endpoint predates the dynamic client
+        # registration rollout, so this stays green against not-yet-upgraded
+        # deployments and starts verifying the moment the endpoint exposes it.
+        if "registration_endpoint" not in doc:
+            self.skipTest(
+                "authorization server does not advertise registration_endpoint yet "
+                "(RFC 7591 dynamic client registration not deployed for this endpoint)"
+            )
+        self.assertEqual(doc["registration_endpoint"], f"{issuer}/register")
+
+    def test_discovery_exposes_supported_scopes(self):
+        # The MCP sources its protected-resource metadata scopes from here.
+        doc = self._discovery()
+        self.assertIsInstance(
+            doc.get("scopes_supported"),
+            list,
+            "discovery missing scopes_supported (MCP cannot advertise scopes)",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_auth.py

@@ -47,6 +47,58 @@ def test_supported_scopes_uses_cache_without_network(self):
             auth._scopes_cache.pop("cachedproj", None)
         self.assertEqual(scopes, ["rows.read", "rows.write"])
 
+    def test_supported_scopes_reads_dcr_enabled_discovery(self):
+        # The authorization server's discovery document now also advertises
+        # `registration_endpoint` (RFC 7591). Sourcing scopes must keep working
+        # against that document — the MCP points clients at this same AS, and
+        # the clients self-register there. This guards the discovery contract
+        # without a network round-trip.
+        discovery = {
+            "issuer": "https://cloud.appwrite.io/v1/oauth2/proj1",
+            "registration_endpoint": "https://cloud.appwrite.io/v1/oauth2/proj1/register",
+            "scopes_supported": ["users.read", "rows.write"],
+        }
+        seen_urls: list[str] = []
+
+        class _FakeResponse:
+            def raise_for_status(self):
+                return None
+
+            def json(self):
+                return discovery
+
+        class _FakeAsyncClient:
+            def __init__(self, *args, **kwargs):
+                pass
+
+            async def __aenter__(self):
+                return self
+
+            async def __aexit__(self, *args):
+                return False
+
+            async def get(self, url):
+                seen_urls.append(url)
+                return _FakeResponse()
+
+        with mock.patch.object(auth.httpx, "AsyncClient", _FakeAsyncClient):
+            try:
+                scopes = asyncio.run(auth.supported_scopes("dcrproj"))
+            finally:
+                auth._scopes_cache.pop("dcrproj", None)
+
+        self.assertEqual(scopes, ["users.read", "rows.write"])
+        # Discovery is read from the OIDC well-known path under the project issuer.
+        self.assertEqual(
+            seen_urls,
+            ["https://cloud.appwrite.io/v1/oauth2/dcrproj/.well-known/openid-configuration"],
+        )
+        # The registration endpoint the MCP points clients to follows `issuer/register`.
+        self.assertEqual(
+            discovery["registration_endpoint"],
+            f"{discovery['issuer']}/register",
+        )
+
     def test_supported_scopes_raises_when_discovery_unreachable(self):
         # Point discovery at an unroutable address so the fetch fails fast.
         with mock.patch.dict(