You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2026/08/06 18:15:54 UTC

(juneau) branch docs updated: docs: OAuth 2.1-secured MCP example (juneau-examples-mcp)

This is an automated email from the ASF dual-hosted git repository.

jamesbognar pushed a commit to branch docs
in repository https://gitbox.apache.org/repos/asf/juneau.git


The following commit(s) were added to refs/heads/docs by this push:
     new d04f52c9b0 docs: OAuth 2.1-secured MCP example (juneau-examples-mcp)
d04f52c9b0 is described below

commit d04f52c9b0a4be6e705df172b858dd0a4a236ad8
Author: James Bognar <ja...@apache.org>
AuthorDate: Thu Aug 6 11:15:34 2026 -0700

    docs: OAuth 2.1-secured MCP example (juneau-examples-mcp)
    
    Co-authored-by: Cursor <cu...@cursor.com>
---
 pages/release-notes/10.0.0.md             | 10 ++++++++++
 pages/topics/11.03.JuneauMcpRecipes.md    |  2 ++
 pages/topics/11.04.JuneauRestServerMcp.md |  2 ++
 pages/topics/11.05.JuneauRestClientMcp.md |  2 ++
 4 files changed, 16 insertions(+)

diff --git a/pages/release-notes/10.0.0.md b/pages/release-notes/10.0.0.md
index 32942e6cfd..6cc19567fd 100644
--- a/pages/release-notes/10.0.0.md
+++ b/pages/release-notes/10.0.0.md
@@ -1002,6 +1002,16 @@ A new example module, `juneau-examples-mcp` (under `juneau-examples/`, alongside
 
 See the [MCP Recipes](/docs/topics/JuneauMcpRecipes#full-example-juneau-examples-mcp), [juneau-rest-server-mcp](/docs/topics/JuneauRestServerMcp), and [juneau-rest-client-mcp](/docs/topics/JuneauRestClientMcp) topics for pointers to the module, and the module's own `README.md` for run instructions.
 
+### MCP `2026-07-28` — OAuth 2.1-secured variant of `juneau-examples-mcp` (`secured/` package)
+
+The example module above gets a second, fully **offline-runnable** variant demonstrating the OAuth 2.1 authorization baseline (TODO-312f) end to end: `org.apache.juneau.examples.mcp.secured` wraps the identical notes service in a live resource-server gate, with a demo authorization server standing in for a real IdP so the whole walkthrough needs no external network access.
+
+- **`SecuredExampleMcpServer extends ExampleMcpServer`** — the entire security story is one `createMcpOptions()` override layering `McpResourceServerConfig` on top of the inherited notes surface: RS auth enabled, `setResource(...)` (the RFC 9728 resource identity / RFC 8707 default audience), a `JwtTokenValidator` checking `iss`/`aud`/`exp`/`nbf` against the offline AS, `addAuthorizationServer(...)`, a baseline `addRequiredScope("mcp.read")`, and SEP-2350 per-operation step-up (`addOpera [...]
+- **`OfflineAuthorizationServer`** — a clearly-marked DEMO-ONLY stand-in AS: a fresh self-generated RSA signing key per run, an offline `JWKSource` handed straight to the validator (no JWKS HTTP fetch), a real RFC 6749 §4.4 client-credentials `/token` endpoint gated by a fixed scope allowlist (`mcp.read`/`mcp.write`, else `invalid_scope`), and an RFC 8414 `/.well-known/oauth-authorization-server` metadata document (issuer = its own loopback base URL, plus `token_endpoint`) enabling genui [...]
+- **`SecuredExampleServer`/`SecuredExampleClient`** — a launcher plus a real, discovery-driven end-to-end client walkthrough: an unauthenticated call rejected with `401` + `WWW-Authenticate: Bearer`, RFC 9728 PRM discovery (`authorization_servers`, `scopes_supported`), RFC 8414 AS-metadata discovery of the `token_endpoint`, a client-credentials token acquisition via `juneau-rest-client-mcp-auth`'s `McpTokenProvider`, a successful `mcp.read` read, the same token rejected with `403 insuffi [...]
+
+See the [OAuth 2.1 recipe](/docs/topics/JuneauMcpRecipes#securing-an-mcp-client-and-server-with-oauth-21-v2-only) for the full walkthrough, and the module's own `README.md` for run instructions.
+
 ### MCP `2026-07-28` — client/server adoption convenience methods
 
 Four small, additive convenience methods land alongside the example module above, each replacing a small piece of repetitive code the example (and real-world adopters) would otherwise repeat at every call site. None deprecates or replaces the lower-level API it sits on top of.
diff --git a/pages/topics/11.03.JuneauMcpRecipes.md b/pages/topics/11.03.JuneauMcpRecipes.md
index 5613f58f42..f2dfacb5a4 100644
--- a/pages/topics/11.03.JuneauMcpRecipes.md
+++ b/pages/topics/11.03.JuneauMcpRecipes.md
@@ -448,6 +448,8 @@ try (var client = McpClient.connect("http://localhost:8080/mcp")) {
 
 This recipe walks both sides of an OAuth 2.1 / MCP `2026-07-28` deployment as one story: turn a v2 MCP endpoint into a protected resource server, then acquire a token on the client and call it. Authorization is **v2-only** and **off by default** — an endpoint that doesn't opt in behaves exactly as before.
 
+**Prefer to start from running code?** The `secured/` package inside [`juneau-examples-mcp`](#full-example-juneau-examples-mcp) is the canonical, copy-me, fully offline realization of this entire recipe — and it ships as part of the same downloadable project zip in the Apache release. `SecuredExampleMcpServer` layers the resource-server config below onto the plain `ExampleMcpServer` with a single `createMcpOptions()` override (baseline `mcp.read`, plus a SEP-2350 per-operation step-up re [...]
+
 **Dependencies.** On the server, add a token-validator module alongside `juneau-rest-server-mcp-v20260728`: `juneau-rest-server-auth-jwt` (JWT/JWKS validation) or `juneau-rest-server-auth-oauth` (RFC 7662 introspection). On the client, add `juneau-rest-client-mcp-auth` alongside `juneau-rest-client-mcp-v20260728`:
 
 ```xml
diff --git a/pages/topics/11.04.JuneauRestServerMcp.md b/pages/topics/11.04.JuneauRestServerMcp.md
index de3c122c73..33a6298df8 100644
--- a/pages/topics/11.04.JuneauRestServerMcp.md
+++ b/pages/topics/11.04.JuneauRestServerMcp.md
@@ -621,6 +621,8 @@ WWW-Authenticate: Bearer realm="mcp", error="insufficient_scope", scope="repo.de
 
 All of the operation's required scopes are emitted in a single `scope=` param (the SEP-2350 "single challenge" SHOULD). Sufficiency is **hierarchy-aware** per the server MUST: a broader granted scope implies its narrower children (granted `repo` satisfies required `repo.delete` / `repo:read`, but granted `repo.read` does *not* satisfy required `repo`). Operations with no configured per-operation scope are unaffected — the baseline alone governs them. The client half of the flow (union th [...]
 
+**See it wired end to end.** `SecuredExampleMcpServer` in the `secured/` package of [`juneau-examples-mcp`](/docs/topics/JuneauMcpRecipes#securing-an-mcp-client-and-server-with-oauth-21-v2-only) applies exactly this pattern with one `createMcpOptions()` override: a baseline `addRequiredScope("mcp.read")` plus `addOperationScope("tools/call", "publishNote", "mcp.write")` (and `deleteNote`) for the step-up, running fully offline against a demo authorization server.
+
 ## Cache Hints (MCP `2026-07-28`, SEP-2549)
 
 The `2026-07-28` adapter (`org.apache.juneau.rest.server.mcp.v20260728`) adds two capabilities on top of the neutral core: SEP-2549 cache hints on five list/read results, and a `resources/templates/list` endpoint. Both are configured statically, at server-construction time — there is no dynamic/per-request cache callback, and neither concept exists on the neutral `juneau-rest-server-mcp` core or the `2025-06-18` adapter.
diff --git a/pages/topics/11.05.JuneauRestClientMcp.md b/pages/topics/11.05.JuneauRestClientMcp.md
index dc2a061dde..f82476ee29 100644
--- a/pages/topics/11.05.JuneauRestClientMcp.md
+++ b/pages/topics/11.05.JuneauRestClientMcp.md
@@ -145,6 +145,8 @@ Fetches an authorization server's metadata as an `OidcMetadata` record (`issuer`
 The full SEP-2351 path-insertion well-known-URI construction (path-bearing issuers, ordered fallbacks) is a deferred enhancement; `OidcDiscoveryClient` currently implements the two-endpoint (RFC 8414 → OIDC) fallback the baseline requires. An OIDC ID token returned alongside an access token is surfaced verbatim on `OAuthToken.idToken()` but is **not validated** in this baseline — do not trust its claims for auth decisions.
 :::
 
+**See it wired end to end.** `SecuredExampleClient` in the `secured/` package of [`juneau-examples-mcp`](/docs/topics/JuneauMcpRecipes#securing-an-mcp-client-and-server-with-oauth-21-v2-only) drives this exact discovery chain with nothing hardcoded — from a `401` challenge through `McpProtectedResourceMetadataClient` (RFC 9728) and `discoverAuthorizationServer(...)` (RFC 8414) to a discovered `token_endpoint` it hands straight to `McpTokenProvider.clientCredentials()`.
+
 ### Dynamic Client Registration (SEP-837)
 
 When you have no pre-registered `client_id`, `McpDynamicClientRegistrar` performs RFC 7591 / OIDC Dynamic Client Registration against an authorization server's `registration_endpoint`, built via `McpDynamicClientRegistrar.create()`. `register()` POSTs the client metadata and returns an immutable `McpClientRegistration` (`clientId`, `clientSecret`, `clientSecretExpiresAt`, `registrationAccessToken`, `registrationClientUri`, `issuer`, `redirectUris`, `applicationType`, `extras`) whose `toS [...]