Enable external MCP Apps with Plugin Programs

Author: reachjalil

docs/features/remote-mcp-apps/README.md

@@ -13,9 +13,10 @@ There are two distribution paths:
    URIs, UI metadata, results, and same-server app calls keep their provider
    meaning.
 2. A self-contained HTML file imported by URL. This is a convenience adapter
-   for a static app bundle. OpenWork caches the bytes, exposes one standard MCP
-   launch tool and one immutable `ui://` resource, and does not invent a second
-   tool or capability protocol.
+   for an externally authored app bundle. OpenWork caches the bytes, exposes
+   one standard MCP launch tool and one immutable `ui://` resource, and may
+   expose an app-specific, app-only Program tool on that same MCP server. The
+   Program, not the browser UI, composes OpenWork Connect capabilities.
 
 Programs remain executable `script` config objects. A Program's generated
 views are MCP resources, but turning a view into a resource does not turn
@@ -87,9 +88,20 @@ ui://openwork/library-apps/{appId}/revisions/{revisionId}/index.html
 ```
 
 The launch result uses ordinary `structuredContent` for the app identity,
-revision, digest, and optional input. There are no OpenWork capability wrapper
-tools. If the app needs tools, publish it with a standard MCP server and add
-that server through Connect.
+revision, digest, optional input, and the name of any available same-server
+Program tool. When Code Mode is enabled, an app-specific `run_program_*` tool
+is advertised with `_meta.ui.visibility: ["app"]`. Its exact name is delivered
+in the launch result rather than embedded in the HTML. It accepts an optional
+exact `programId` or uses the member's selected Program, and rejects Programs
+outside the app's owning Plugin. Normal host approval and Plugin access checks
+still apply. The Program executes server-side and receives the member's
+authorized Connect tool tree; the HTML receives only the Program result.
+
+This is the only OpenWork-specific execution affordance in the URL adapter.
+The transport remains standard MCP `tools/call`, and the tool stays on the
+same server as the `ui://` resource. OpenWork does not let a browser app call
+tools on another MCP server. Apps distributed with their own MCP server keep
+using that server's native tools and should be added through Connect.
 
 ## Authoring and execution contract
 
@@ -110,6 +122,8 @@ The execution contract is intentionally portable:
 - local development may provide mock tool results directly to the UI;
 - production MCP execution supplies input and results through the MCP Apps
   bridge;
+- an imported app can call the advertised same-server Program tool, while the
+  Program calls OpenWork Connect capabilities server-side;
 - credentials remain in the MCP host/Connect connection and never enter the
   HTML resource;
 - an app calls only tools from its originating MCP server;
@@ -132,18 +146,24 @@ For a static bundle:
    validation and shows the resolved source, size, and digest.
 3. Import and activate. The adapter appears as an App inside its owning Plugin
    and shares through the existing Plugin/Marketplace access model.
-4. Refresh caches a new immutable draft without changing the active revision.
-5. Activate or roll back explicitly. Retire removes the launch tool from agent
+4. To give the UI Connect-backed behavior, open **Manage Plugin**, add a Code
+   Mode Program to that Plugin, and select it. The app-specific tool rejects a
+   selected Program from any other Plugin.
+5. Refresh caches a new immutable draft without changing the active revision.
+6. Activate or roll back explicitly. Retire removes the launch tool from agent
    discovery without deleting cached revisions; restore re-exposes the active
    revision.
-6. Download always returns the exact cached HTML revision, so the installed
+7. Download always returns the exact cached HTML revision, so the installed
    copy remains usable after the source URL disappears.
 
-The static adapter is independent of `codemodeScripts`. Runtime discovery is
-gated by `DEN_REMOTE_MCP_APPS_ENABLED` until a compatible Desktop host is
-released. Normal MCP Apps delivered by an existing Connect server use the
-standard Connect and Desktop MCP host paths rather than this static-adapter
-flag.
+The static adapter is independently disableable with
+`DEN_REMOTE_MCP_APPS_ENABLED`, but defaults on after the compatible Desktop
+host release. `DEN_GENERATED_ARTIFACT_VIEWS_ENABLED` remains off by default;
+imported UI availability does not let agents author or compile MCP App UI in
+OpenWork. The optional Program tool is present only for organizations with
+`codemodeScripts` enabled. Normal MCP Apps delivered by an existing Connect
+server use the standard Connect and Desktop MCP host paths rather than this
+static-adapter flag.
 
 ## Host security and compatibility
 

ee/apps/den-api/.env.example

@@ -35,9 +35,9 @@ DEN_MCP_ADDITIONAL_RESOURCES=
 # Enable only after deploying a Desktop release that delivers render-tool
 # structuredContent through the stable MCP Apps bridge after initialization.
 DEN_GENERATED_ARTIFACT_VIEWS_ENABLED=false
-# Enable only after deploying a Desktop release with the stable MCP Apps host.
-# This is independent of Code Mode and generated Artifact view rollout.
-DEN_REMOTE_MCP_APPS_ENABLED=false
+# The stable Desktop MCP Apps host supports imported apps by default. Set false
+# for an operator rollback. This does not enable generated Artifact views.
+DEN_REMOTE_MCP_APPS_ENABLED=true
 # Leave unset on hosted/multi-tenant deployments. Set to 1 only when Den runs
 # inside a private network and your MCP servers are on private addresses.
 # OPENWORK_DEV_MODE=1 already exempts local dev.

ee/apps/den-api/src/env.ts

@@ -435,10 +435,10 @@ const mcpConnectionsGatingEnabled =
 const generatedArtifactViewsEnabled =
   (parsed.DEN_GENERATED_ARTIFACT_VIEWS_ENABLED ?? "false").trim().toLowerCase() === "true"
 
-// Imported apps use the same stable Desktop MCP Apps bridge but have an
-// independent lifecycle from generated Artifact views and Code Mode Programs.
+// Imported apps use the released stable Desktop MCP Apps bridge and remain
+// independently disableable without enabling agent-authored generated views.
 const remoteMcpAppsEnabled =
-  (parsed.DEN_REMOTE_MCP_APPS_ENABLED ?? "false").trim().toLowerCase() === "true"
+  (parsed.DEN_REMOTE_MCP_APPS_ENABLED ?? "true").trim().toLowerCase() === "true"
 
 const devMode = (parsed.OPENWORK_DEV_MODE ?? "0").trim() === "1"
 const botIdProtectionEnabled = (parsed.DEN_BOTID_PROTECTION_ENABLED ?? "0").trim() === "1"

ee/apps/den-api/src/mcp/agent.ts

@@ -171,7 +171,8 @@ const programRunOutputSchema = z.object({
 
 export const AGENT_MCP_INSTRUCTIONS = [
   "This OpenWork Cloud MCP server uses standard MCP tools, resources, structured results, and list-changed notifications. OpenWork Programs and Remote MCP Apps add only durable identity, Plugin containment, access, retained resources and results, selection, and lifecycle around those MCP primitives.",
-  "When Remote MCP App delivery is enabled, active apps in the member's Library appear as individually named launch tools backed by immutable ui:// resources.",
+  "MCP App UI is authored and bundled outside OpenWork. Agents do not author, compile, or save MCP App UI in OpenWork. Active imported apps in the member's Library appear as individually named launch tools backed by immutable ui:// resources.",
+  "An imported app may call the app-visible Program tool named in its launch structuredContent through the standard same-server MCP Apps bridge. That tool runs an exact accessible Program inside the app's Plugin, or the member's selected Program when no id is supplied; the Program is the only layer that reaches OpenWork Connect capabilities.",
   "A Program is an immutable-versioned Code Mode Script config object inside an OpenWork Connect Plugin. Organizations with Code Mode scripts enabled receive execute_capability_script, the backwards-compatible render_dynamic_artifact MCP App tool, and a constant-size Program catalog: search_programs, select_program, and clear_program_selection.",
   "To use a Program, search by Library metadata, select one exact accessible Program, then refresh the tool catalog. The selected context exposes run_selected_program and render_selected_program; rendering returns an Artifact as fallback text plus retained data in structuredContent and binds the exact immutable MCP App resource URI in the tool definition.",
   "When a member asks to keep a successful Code Mode result, save it as a Program inside the existing OpenWork Connect Plugin they name by passing that pluginId to the Code Mode save operation. Omit pluginId only for a private Program in the member's My Programs Plugin. A Program inherits discovery and sharing from its Plugin and any Marketplace containing that Plugin; do not create a separate Program package or marketplace entry.",
@@ -187,7 +188,6 @@ export const AGENT_MCP_INSTRUCTIONS = [
   "External MCP matches include the provider-advertised argumentsSchema, schemaDigest, and invocation.argumentsField. Put an object matching argumentsSchema in execute_capability.body and copy schemaDigest into execute_capability.schemaDigest.",
   "OpenWork always attempts the downstream provider call when local schema checks find a mismatch. schemaGuidance is advisory and appears alongside the provider result: if the provider succeeded, accept that result and do not retry solely because of the warning; if it failed, use the warning to correct the arguments or search again.",
   "If the provider returns invalid_capability_arguments, correct the listed issues and retry once with changed arguments; never retry the same arguments unchanged. If it returns unknown_capability, call search_capabilities again before retrying.",
-  "When save_artifact_view is advertised, create or update the saved Script with an explicit JSON Schema outputSchema matching its returned data before calling it. React is injected into view source, so use React APIs without imports and render only the supplied data prop. A failed view build includes diagnostics: change the source once and retry with the returned artifactViewId; do not search for a different Artifact tool or call render_dynamic_artifact. After a successful save, call the exact render_artifact_* or preview_artifact_* tool named in its result.",
   "When a match has kind connection_status, name connectionStatus.connectionName and relay connectionStatus.action exactly. Distinguish the member's Your Connections page, the organization Connections dashboard, and the provider's own admin console.",
   "Connection probes are live. After the requested human fixes that connector, search again in the same task; otherwise do not retry unchanged or improvise workarounds through other tools.",
 ].join("\n")
@@ -449,6 +449,85 @@ export function registerAgentMcpRoutes<T extends { Variables: RequestIdVariables
       }
     }
     const artifactContext = codemodeEnabled ? libraryContext : null
+    const executeRemoteAppProgram = artifactContext
+      ? async ({ programId, pluginId, input }: { programId?: string; pluginId: string; input?: unknown }) => {
+          try {
+            const resolvedProgramId = programId
+              ?? (await getProgramAgentSelection(artifactContext))?.programId
+            if (!resolvedProgramId) {
+              return {
+                isError: true,
+                content: textContent(JSON.stringify({
+                  error: "program_not_selected",
+                  message: "Select a Program in OpenWork before this MCP App runs it, or pass an exact accessible programId.",
+                })),
+              }
+            }
+            const detail = await getProgramDetail({
+              context: artifactContext,
+              configObjectId: resolvedProgramId,
+            })
+            if (detail.script.pluginId !== pluginId) {
+              return {
+                isError: true,
+                content: textContent(JSON.stringify({
+                  error: "program_not_in_app_plugin",
+                  message: "The selected Program is not inside this MCP App's Plugin.",
+                })),
+              }
+            }
+            await requirePluginArchResourceRole({
+              context: artifactContext,
+              requireFreshSession: false,
+              resourceId: normalizeDenTypeId("configObject", resolvedProgramId),
+              resourceKind: "config_object",
+              role: "editor",
+            })
+            const execution = await executeMarketplaceCapability({
+              organizationId: principal.organizationId,
+              member: memberIdentity,
+              pluginId: detail.script.pluginId,
+              configObjectId: detail.script.configObjectId,
+              configObjectVersionId: detail.script.currentVersion.id,
+              body: input,
+              codemodeEnabled: true,
+              validateScriptOutput: true,
+              buildTools: () => buildCapabilityToolTree(capabilityContext),
+            })
+            if (!execution.ok || execution.result.status !== "executed") {
+              const message = execution.ok
+                ? execution.result.hint ?? "The Program could not run."
+                : execution.message
+              return {
+                isError: true,
+                content: textContent(JSON.stringify({ error: "program_run_failed", message })),
+              }
+            }
+            const result = {
+              status: "succeeded" as const,
+              value: execution.result.value,
+              receiptId: execution.result.receiptId ?? null,
+              resultDigest: execution.result.resultDigest ?? null,
+            }
+            return {
+              content: textContent(JSON.stringify(result, null, 2)),
+              structuredContent: result,
+            }
+          } catch (error) {
+            const unavailable = error instanceof PluginArchAuthorizationError
+              || (error instanceof Error && error.message.includes("not_found"))
+            return {
+              isError: true,
+              content: textContent(JSON.stringify({
+                error: unavailable ? "program_not_found" : "program_run_failed",
+                message: unavailable
+                  ? "The Program is not available to this member."
+                  : "The Program could not run.",
+              })),
+            }
+          }
+        }
+      : undefined
     if (method === "initialize" || method === "resources/list" || method === "resources/read") {
       remoteSkills = [
         ...listBuiltinSkillDescriptors(),
@@ -473,6 +552,7 @@ export function registerAgentMcpRoutes<T extends { Variables: RequestIdVariables
           })
           return { html: loaded.html, payload: loaded.payload }
         },
+        runProgram: executeRemoteAppProgram,
       })
     }
     if (method === "initialize" || method === "resources/list" || method === "resources/read") {

ee/apps/den-api/src/mcp/remote-mcp-apps.ts

@@ -23,6 +23,10 @@ export function remoteMcpAppLaunchToolName(configObjectId: string) {
   return `launch_remote_app_${stableSuffix(configObjectId)}`
 }
 
+export function remoteMcpAppRunProgramToolName(configObjectId: string) {
+  return `run_program_${stableSuffix(configObjectId)}`
+}
+
 function resourceMeta(revision: Pick<ActiveRemoteMcpApp, "payload">): { ui: McpUiResourceMeta; resourceDigest: string } {
   return {
     ui: { csp: revision.payload.resource.csp, prefersBorder: true },
@@ -37,9 +41,47 @@ export function registerAgentRemoteMcpApps(input: {
     html: string
     payload: ActiveRemoteMcpApp["payload"]
   }>
+  runProgram?: (request: {
+    appConfigObjectId: string
+    pluginId: string
+    programId?: string
+    input?: unknown
+  }) => Promise<{
+    content: Array<{ type: "text"; text: string }>
+    structuredContent?: Record<string, unknown>
+    isError?: boolean
+  }>
 }) {
+  const runProgram = input.runProgram
   for (const app of input.apps) {
     const metadata = app.payload.metadata
+    const runProgramToolName = remoteMcpAppRunProgramToolName(app.app.configObjectId)
+    if (runProgram) {
+      registerAppTool(
+        input.server,
+        runProgramToolName,
+        {
+          title: `Run ${metadata.name} Program`,
+          description: [
+            `Run a Code Mode Program inside the ${metadata.name} Plugin through OpenWork Connect.`,
+            "Omit programId to use the member's selected Program, or pass an exact accessible Program id from this Plugin.",
+            "This app-only tool stays on the same MCP server as the imported UI resource; the Program owns all downstream Connect capability calls.",
+          ].join(" "),
+          annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+          inputSchema: z.object({
+            programId: z.string().trim().min(1).max(160).optional(),
+            input: z.unknown().optional(),
+          }),
+          _meta: { ui: { visibility: ["app"] } },
+        },
+        async ({ programId, input: programInput }) => runProgram({
+          appConfigObjectId: app.app.configObjectId,
+          pluginId: app.app.pluginId,
+          ...(programId ? { programId } : {}),
+          ...(programInput === undefined ? {} : { input: programInput }),
+        }),
+      )
+    }
     for (const revision of app.revisions) {
       const metadata = resourceMeta(revision)
       registerAppResource(
@@ -91,6 +133,9 @@ export function registerAgentRemoteMcpApps(input: {
             revisionId: app.versionId,
             resourceDigest: app.payload.resource.digest,
           },
+          ...(input.runProgram ? {
+            serverTools: { runProgram: runProgramToolName },
+          } : {}),
           ...(launchInput === undefined ? {} : { input: launchInput }),
         }
         return {

ee/apps/den-api/test/agent-codemode-script.test.ts

@@ -148,9 +148,12 @@ afterAll(() => {
 test("does not register execute_capability_script when the org flag is off", async () => {
   const tools = listedToolNames(await rpc(buildApp(), "tools/list"))
   expect(tools).not.toContain("execute_capability_script")
+  expect(tools).not.toContain("save_artifact_view")
+  expect(tools).not.toContain("activate_artifact_view_revision")
+  expect(tools).not.toContain("retire_artifact_view")
 })
 
-test("registers execute_capability_script when the org flag is on", async () => {
+test("registers Code Mode without enabling agent-authored MCP App views", async () => {
   organizationMetadata = { capabilities: { codemodeScripts: true } }
   const tools = listedTools(await rpc(buildApp(), "tools/list"))
   const names = tools.flatMap((tool) => typeof tool.name === "string" ? [tool.name] : [])
@@ -159,6 +162,9 @@ test("registers execute_capability_script when the org flag is on", async () =>
   expect(names).toContain("search_programs")
   expect(names).toContain("select_program")
   expect(names).toContain("clear_program_selection")
+  expect(names).not.toContain("save_artifact_view")
+  expect(names).not.toContain("activate_artifact_view_revision")
+  expect(names).not.toContain("retire_artifact_view")
   expect(isRecord(tools.find((tool) => tool.name === "search_programs")?.outputSchema)).toBe(true)
   expect(isRecord(tools.find((tool) => tool.name === "select_program")?.outputSchema)).toBe(true)
   expect(isRecord(tools.find((tool) => tool.name === "clear_program_selection")?.outputSchema)).toBe(true)