@@ -183,6 +183,57 @@ On session creation and a **cold** resume, disabled servers are not started and
183183the runtime does not initiate their authentication. A resident resume cannot
184184undo a server that the runtime has already spawned. Names are matched exactly.
185185
186+ ## Listing and retrieving prompts
187+
188+ The experimental generated MCP namespace exposes the wire JSON-RPC methods
189+ ` session.mcp.prompts.list ` and ` session.mcp.prompts.get ` . Use the language-specific
190+ SDK accessors below to call them. These methods target one connected server in the
191+ current session; they do not combine results from multiple servers.
192+
193+ | SDK | List prompts | Get a prompt |
194+ | --- | --- | --- |
195+ | Node.js | ` session.rpc.mcp.prompts.list(...) ` | ` session.rpc.mcp.prompts.get(...) ` |
196+ | Python | ` session.rpc.mcp.prompts.list(...) ` | ` session.rpc.mcp.prompts.get(...) ` |
197+ | Go | ` session.RPC.MCP.Prompts().List(...) ` | ` session.RPC.MCP.Prompts().Get(...) ` |
198+ | .NET | ` session.Rpc.Mcp.Prompts.ListAsync(...) ` | ` session.Rpc.Mcp.Prompts.GetAsync(...) ` |
199+ | Java | ` session.getRpc().mcp.prompts.list(...) ` | ` session.getRpc().mcp.prompts.get(...) ` |
200+ | Rust | ` session.rpc().mcp().prompts().list(...) ` | ` session.rpc().mcp().prompts().get(...) ` |
201+
202+ Listing requires ` serverName ` and accepts an optional opaque ` cursor ` . Each
203+ call returns one page of typed prompt definitions and an optional ` nextCursor ` .
204+ Pass that cursor in another list call to request the next page. Definitions
205+ include names, optional titles and descriptions, and argument definitions.
206+ An omitted argument ` required ` flag remains distinct from ` false ` .
207+
208+ Getting a prompt requires ` serverName ` and ` promptName ` , with an optional
209+ ` arguments ` dictionary whose values are strings. Omitting ` arguments ` leaves the
210+ MCP request's arguments absent; passing ` {} ` sends an explicitly empty dictionary.
211+ The runtime preserves this distinction for the server. The result contains an optional
212+ description and ordered messages with typed roles and opaque JSON ` content ` .
213+ Inspect each content block's ` type ` before interpreting it; content is not
214+ flattened into text. Nested resources, annotations, metadata, unfamiliar content
215+ types, and additional content fields retain their JSON structure. Server
216+ extensions on typed descriptors, messages, and result envelopes are available under
217+ ` additionalProperties ` . A server extension itself named ` additionalProperties `
218+ is preserved as an entry inside that map, not merged into it.
219+ The protocol's top-level ` resultType: "complete" ` discriminator is consumed by
220+ the runtime; it is not returned as an SDK field or a server extension.
221+ Requests fail explicitly if the runtime cannot preserve the raw response,
222+ including stdio response frames exceeding the 1 MiB capture limit.
223+
224+ The returned prompt messages are not automatically sent to the model or used to
225+ execute tools or fetch referenced resources. Your application decides how to
226+ use the result.
227+ While generating that result, an MCP server can request sampling or elicitation
228+ through multi round-trip continuations. These requests use the same configured
229+ host responders as other MCP operations; prompt retrieval does not grant
230+ additional permission or bypass the host's decision. A missing responder or
231+ responder error fails the request, and an elicitation decline is returned to the
232+ server unchanged. State-only continuations do not invoke either responder.
233+
234+ After an existing ` mcp.prompts.list_changed ` session event, list the named
235+ server's prompts again to refresh your application's view.
236+
186237## Tool configuration
187238
188239You can control which tools are available to an MCP server using the ` tools ` field.
@@ -295,6 +346,53 @@ directories for different applications.
295346| ` tools ` | ` string[] ` | No | Tools to enable |
296347| ` timeout ` | ` number ` | No | Timeout in milliseconds |
297348
349+ ## OAuth ownership for remote servers
350+
351+ Choose one OAuth ownership model for each authentication attempt:
352+
353+ 1 . ** Runtime-managed loopback** : Call ` session.mcp.oauth.login ` without a
354+ redirect URI. The runtime opens a local callback listener and owns discovery,
355+ PKCE, state validation, token exchange, persistence, refresh, and reconnect.
356+ 1 . ** Runtime-managed hosted callback** : Call ` session.mcp.oauth.login ` with a
357+ trusted public HTTPS redirect URI. Your host receives the callback, but the
358+ runtime continues to own the OAuth protocol and credentials.
359+ 1 . ** Host-managed OAuth** : Use the SDK's MCP authentication request handler and
360+ return a host-acquired access token. Your host owns authorization and refresh.
361+
362+ Do not register a host-managed OAuth handler for an authentication attempt that
363+ uses a runtime-managed hosted callback. Wait until the remote server enters the
364+ ` needs-auth ` state, then call the generated ` session.rpc.mcp.oauth.login ` method
365+ directly with the server name and callback URI:
366+
367+ ``` jsonc
368+ {
369+ " serverName" : " remote-mcp" ,
370+ " redirectUri" : " https://agent.example.com/oauth/callback"
371+ }
372+ ```
373+
374+ The selected static, CIMD, or dynamically registered OAuth client must advertise
375+ that exact URI. The URI must use HTTPS and must not contain a query or fragment.
376+ When browser interaction is required, the result contains ` authorizationUrl `
377+ and ` authorizationId ` . Open ` authorizationUrl ` in the user's browser and retain
378+ ` authorizationId ` with the target session.
379+
380+ After the authorization server redirects to your endpoint, call the generated
381+ ` session.rpc.mcp.oauth.complete ` method:
382+
383+ ``` jsonc
384+ {
385+ " authorizationId" : " <opaque-state>" ,
386+ " callbackUrl" : " https://agent.example.com/oauth/callback?code=...&state=..."
387+ }
388+ ```
389+
390+ Construct ` callbackUrl ` from the configured public redirect origin and path plus
391+ the callback's original query. Do not pass an internal service URL or trust
392+ client-supplied ` Forwarded ` or ` X-Forwarded-* ` headers. The runtime validates the
393+ origin, port, path, state, and OAuth response before accepting delivery. Token
394+ exchange, persistence, and MCP reconnect then continue asynchronously.
395+
298396## Session-scoped MCP diagnostics
299397
300398Set ` diagnostics: { sources: { mcp: { level: "debug" } } } ` when you create or
0 commit comments