feat: add enableMcpApps support to Java SDK

Mirrors the MCP Apps (SEP-1865) opt-in already wired into Node, Python,
Go, .NET, and Rust:

- SessionConfig / ResumeSessionConfig: enableMcpApps field with
  isEnableMcpApps / setEnableMcpApps accessors and copy() inclusion
- CreateSessionRequest / ResumeSessionRequest: requestMcpApps wire field
  with getter/setter/clearer (Boolean nullable, matches requestElicitation)
- SessionUiCapabilities: mcpApps response field with getter/setter/clearer
- SessionRequestBuilder: wires config.isEnableMcpApps() -> requestMcpApps
  on both create and resume paths
- CopilotClient: warnIfMcpAppsDropped helper logs when the consumer
  requested the opt-in but the runtime did not advertise it back (runtime
  silently drops the opt-in when its MCP_APPS feature flag /
  COPILOT_MCP_APPS env override is unset)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mattdholloway

java/mvnw

@@ -34,6 +34,7 @@
 import com.github.copilot.sdk.json.PingResponse;
 import com.github.copilot.sdk.json.ResumeSessionConfig;
 import com.github.copilot.sdk.json.ResumeSessionResponse;
+import com.github.copilot.sdk.json.SessionCapabilities;
 import com.github.copilot.sdk.json.SessionConfig;
 import com.github.copilot.sdk.json.SessionLifecycleHandler;
 import com.github.copilot.sdk.json.SessionListFilter;
@@ -290,6 +291,31 @@ private static boolean isUnsupportedConnectMethod(JsonRpcException ex) {
         return ex.getCode() == METHOD_NOT_FOUND_ERROR_CODE || "Unhandled method connect".equals(ex.getMessage());
     }
 
+    /**
+     * Logs a warning when the consumer set {@code enableMcpApps=true} on
+     * create/resume but the runtime did not advertise
+     * {@code capabilities.ui.mcpApps} in the response. The runtime silently
+     * drops the opt-in when its {@code MCP_APPS} feature flag (or
+     * {@code COPILOT_MCP_APPS=true} env override) is unset, so without this
+     * warning a consumer trying to use MCP Apps would see no error -- just
+     * tools that never expose {@code _meta.ui.resourceUri}.
+     */
+    private static void warnIfMcpAppsDropped(boolean requested, SessionCapabilities capabilities) {
+        if (!requested) {
+            return;
+        }
+        boolean advertised = capabilities != null
+                && capabilities.getUi() != null
+                && capabilities.getUi().getMcpApps().orElse(false);
+        if (advertised) {
+            return;
+        }
+        LOG.warning(
+                "enableMcpApps was requested but the runtime did not advertise capabilities.ui.mcpApps. "
+                        + "The runtime's MCP_APPS feature flag or COPILOT_MCP_APPS=true environment override is "
+                        + "likely unset; the MCP Apps surface is unavailable for this session.");
+    }
+
     /**
      * Disconnects from the Copilot server and closes all active sessions.
      * <p>
@@ -467,6 +493,7 @@ public CompletableFuture<CopilotSession> createSession(SessionConfig config) {
                         rpcNanos);
                 session.setWorkspacePath(response.workspacePath());
                 session.setCapabilities(response.capabilities());
+                warnIfMcpAppsDropped(config.isEnableMcpApps(), response.capabilities());
                 // If the server returned a different sessionId (e.g. a v2 CLI that ignores
                 // the client-supplied ID), re-key the sessions map.
                 String returnedId = response.sessionId();
@@ -552,6 +579,7 @@ public CompletableFuture<CopilotSession> resumeSession(String sessionId, ResumeS
                         rpcNanos);
                 session.setWorkspacePath(response.workspacePath());
                 session.setCapabilities(response.capabilities());
+                warnIfMcpAppsDropped(config.isEnableMcpApps(), response.capabilities());
                 // If the server returned a different sessionId than what was requested, re-key.
                 String returnedId = response.sessionId();
                 if (returnedId != null && !returnedId.equals(sessionId)) {

java/src/main/java/com/github/copilot/sdk/CopilotClient.java

@@ -144,6 +144,9 @@ static CreateSessionRequest buildCreateRequest(SessionConfig config, String sess
         if (config.getOnElicitationRequest() != null) {
             request.setRequestElicitation(true);
         }
+        if (config.isEnableMcpApps()) {
+            request.setRequestMcpApps(true);
+        }
         if (config.getOnExitPlanMode() != null) {
             request.setRequestExitPlanMode(true);
         }
@@ -238,6 +241,9 @@ static ResumeSessionRequest buildResumeRequest(String sessionId, ResumeSessionCo
         if (config.getOnElicitationRequest() != null) {
             request.setRequestElicitation(true);
         }
+        if (config.isEnableMcpApps()) {
+            request.setRequestMcpApps(true);
+        }
         if (config.getOnExitPlanMode() != null) {
             request.setRequestExitPlanMode(true);
         }

java/src/main/java/com/github/copilot/sdk/SessionRequestBuilder.java

@@ -112,6 +112,9 @@ public final class CreateSessionRequest {
     @JsonProperty("requestElicitation")
     private Boolean requestElicitation;
 
+    @JsonProperty("requestMcpApps")
+    private Boolean requestMcpApps;
+
     @JsonProperty("requestExitPlanMode")
     private Boolean requestExitPlanMode;
 
@@ -488,6 +491,21 @@ public void clearRequestElicitation() {
         this.requestElicitation = null;
     }
 
+    /** Gets the requestMcpApps flag. @return the flag */
+    public Boolean getRequestMcpApps() {
+        return requestMcpApps;
+    }
+
+    /** Sets the requestMcpApps flag. @param requestMcpApps the flag */
+    public void setRequestMcpApps(boolean requestMcpApps) {
+        this.requestMcpApps = requestMcpApps;
+    }
+
+    /** Clears the requestMcpApps setting, reverting to the default behavior. */
+    public void clearRequestMcpApps() {
+        this.requestMcpApps = null;
+    }
+
     /** Gets the requestExitPlanMode flag. @return the flag */
     public Boolean getRequestExitPlanMode() {
         return requestExitPlanMode;

java/src/main/java/com/github/copilot/sdk/json/CreateSessionRequest.java

@@ -70,6 +70,7 @@ public class ResumeSessionConfig {
     private ElicitationHandler onElicitationRequest;
     private ExitPlanModeHandler onExitPlanMode;
     private AutoModeSwitchHandler onAutoModeSwitch;
+    private boolean enableMcpApps;
     private String gitHubToken;
     private String remoteSession;
 
@@ -806,6 +807,31 @@ public ResumeSessionConfig setOnElicitationRequest(ElicitationHandler onElicitat
         return this;
     }
 
+    /**
+     * Returns whether MCP Apps (SEP-1865) UI passthrough is enabled on resume.
+     *
+     * @return {@code true} if the consumer has opted into MCP Apps, otherwise
+     *         {@code false}
+     * @see #setEnableMcpApps(boolean)
+     */
+    public boolean isEnableMcpApps() {
+        return enableMcpApps;
+    }
+
+    /**
+     * Enables MCP Apps (SEP-1865) UI passthrough on the resumed session. See
+     * {@link SessionConfig#setEnableMcpApps(boolean)} for full semantics
+     * (runtime gate, capability inspection, renderer requirement).
+     *
+     * @param enableMcpApps
+     *            {@code true} to opt into MCP Apps support on resume
+     * @return this config for method chaining
+     */
+    public ResumeSessionConfig setEnableMcpApps(boolean enableMcpApps) {
+        this.enableMcpApps = enableMcpApps;
+        return this;
+    }
+
     /**
      * Gets the exit-plan-mode request handler.
      *
@@ -963,6 +989,7 @@ public ResumeSessionConfig clone() {
         copy.onElicitationRequest = this.onElicitationRequest;
         copy.onExitPlanMode = this.onExitPlanMode;
         copy.onAutoModeSwitch = this.onAutoModeSwitch;
+        copy.enableMcpApps = this.enableMcpApps;
         copy.gitHubToken = this.gitHubToken;
         copy.remoteSession = this.remoteSession;
         return copy;

java/src/main/java/com/github/copilot/sdk/json/ResumeSessionConfig.java

@@ -116,6 +116,9 @@ public final class ResumeSessionRequest {
     @JsonProperty("requestElicitation")
     private Boolean requestElicitation;
 
+    @JsonProperty("requestMcpApps")
+    private Boolean requestMcpApps;
+
     @JsonProperty("requestExitPlanMode")
     private Boolean requestExitPlanMode;
 
@@ -512,6 +515,21 @@ public void clearRequestElicitation() {
         this.requestElicitation = null;
     }
 
+    /** Gets the requestMcpApps flag. @return the flag */
+    public Boolean getRequestMcpApps() {
+        return requestMcpApps;
+    }
+
+    /** Sets the requestMcpApps flag. @param requestMcpApps the flag */
+    public void setRequestMcpApps(boolean requestMcpApps) {
+        this.requestMcpApps = requestMcpApps;
+    }
+
+    /** Clears the requestMcpApps setting, reverting to the default behavior. */
+    public void clearRequestMcpApps() {
+        this.requestMcpApps = null;
+    }
+
     /** Gets the requestExitPlanMode flag. @return the flag */
     public Boolean getRequestExitPlanMode() {
         return requestExitPlanMode;

java/src/main/java/com/github/copilot/sdk/json/ResumeSessionRequest.java

@@ -70,6 +70,7 @@ public class SessionConfig {
     private ElicitationHandler onElicitationRequest;
     private ExitPlanModeHandler onExitPlanMode;
     private AutoModeSwitchHandler onAutoModeSwitch;
+    private boolean enableMcpApps;
     private String gitHubToken;
     private String remoteSession;
     private CloudSessionOptions cloud;
@@ -860,6 +861,50 @@ public SessionConfig setOnElicitationRequest(ElicitationHandler onElicitationReq
         return this;
     }
 
+    /**
+     * Returns whether MCP Apps (SEP-1865) UI passthrough is enabled on this
+     * session.
+     *
+     * @return {@code true} if the consumer has opted into MCP Apps, otherwise
+     *         {@code false}
+     * @see #setEnableMcpApps(boolean)
+     */
+    public boolean isEnableMcpApps() {
+        return enableMcpApps;
+    }
+
+    /**
+     * Enables MCP Apps (SEP-1865) UI passthrough on this session.
+     * <p>
+     * When {@code true} <b>and</b> the runtime has MCP Apps enabled (via the
+     * {@code MCP_APPS} feature flag or {@code COPILOT_MCP_APPS=true} environment
+     * override), the runtime adds the {@code mcp-apps} capability to the session,
+     * which causes it to advertise the
+     * {@code extensions.io.modelcontextprotocol/ui} extension to MCP servers (so
+     * they expose {@code _meta.ui.resourceUri} on tools) and to expose the
+     * {@code session.rpc.mcp.apps.{listTools,callTool,readResource,
+     * setHostContext,getHostContext,diagnose}} JSON-RPC methods.
+     * <p>
+     * If the runtime gate is off, the opt-in is silently dropped server-side (the
+     * runtime logs a warning); the session is created normally but the MCP Apps
+     * surface is unavailable. Inspect {@link SessionUiCapabilities#getMcpApps()} on
+     * {@link com.github.copilot.sdk.CopilotSession#getCapabilities()} to detect
+     * this.
+     * <p>
+     * SDK consumers MUST set this to {@code true} only when they have an iframe
+     * renderer that can display {@code ui://} MCP App bundles. Setting it without
+     * a renderer will cause MCP servers to register UI-enabled tool variants the
+     * consumer cannot display.
+     *
+     * @param enableMcpApps
+     *            {@code true} to opt into MCP Apps support
+     * @return this config instance for method chaining
+     */
+    public SessionConfig setEnableMcpApps(boolean enableMcpApps) {
+        this.enableMcpApps = enableMcpApps;
+        return this;
+    }
+
     /**
      * Gets the exit-plan-mode request handler.
      *
@@ -1057,6 +1102,7 @@ public SessionConfig clone() {
         copy.onElicitationRequest = this.onElicitationRequest;
         copy.onExitPlanMode = this.onExitPlanMode;
         copy.onAutoModeSwitch = this.onAutoModeSwitch;
+        copy.enableMcpApps = this.enableMcpApps;
         copy.gitHubToken = this.gitHubToken;
         copy.remoteSession = this.remoteSession;
         copy.cloud = this.cloud;

java/src/main/java/com/github/copilot/sdk/json/SessionConfig.java

@@ -21,6 +21,9 @@ public class SessionUiCapabilities {
     @JsonProperty("elicitation")
     private Boolean elicitation;
 
+    @JsonProperty("mcpApps")
+    private Boolean mcpApps;
+
     /**
      * Returns whether the host supports interactive elicitation dialogs.
      *
@@ -53,4 +56,41 @@ public SessionUiCapabilities clearElicitation() {
         return this;
     }
 
+    /**
+     * Returns whether the runtime has accepted the session's MCP Apps (SEP-1865)
+     * opt-in. Present and {@code true} when the consumer set
+     * {@code enableMcpApps=true} on create/resume <b>and</b> the runtime's
+     * {@code MCP_APPS} feature flag (or {@code COPILOT_MCP_APPS=true} env
+     * override) is on. Otherwise empty or {@code false}, indicating the runtime
+     * silently dropped the opt-in.
+     *
+     * @return an {@link Optional} containing the boolean value, or empty if not set
+     */
+    @JsonIgnore
+    public Optional<Boolean> getMcpApps() {
+        return Optional.ofNullable(mcpApps);
+    }
+
+    /**
+     * Sets whether the runtime has accepted the MCP Apps opt-in.
+     *
+     * @param mcpApps
+     *            {@code true} if MCP Apps is enabled for this session
+     * @return this instance for method chaining
+     */
+    public SessionUiCapabilities setMcpApps(boolean mcpApps) {
+        this.mcpApps = mcpApps;
+        return this;
+    }
+
+    /**
+     * Clears the mcpApps setting.
+     *
+     * @return this instance for method chaining
+     */
+    public SessionUiCapabilities clearMcpApps() {
+        this.mcpApps = null;
+        return this;
+    }
+
 }