@kya-os/mcp-i-cloudflare 1.7.76 → 1.8.1

package/dist/agent.js

@@ -24,8 +24,11 @@ import { OAuthSecurityService } from "./services/oauth-security.service";
 import { WorkersFetchProvider } from "./providers/storage";
 import { resolveClientIdentity, } from "./services/kta-client-lookup";
 import { findKnownClient } from "./utils/known-clients";
+import { didKeyFragment } from "@kya-os/mcp-i-core/utils/did-helpers";
 import { calculateDOInstanceId, parseDORoutingStrategy, parseDOShardCount, } from "./utils/do-routing";
 import { defaultProviderRegistry, } from "@kya-os/provider-registry";
+import { hasApiKeyAuthorization, AuthRequiredError } from "@kya-os/contracts/tool-protection";
+import { VaultResolver } from "./services/vault-resolver";
 // CRITICAL: Force OAuth registry evaluation at module load time
 // This creates an observable side effect that esbuild cannot tree-shake
 // Without this, esbuild may eliminate oauth-service-registry.ts entirely
@@ -65,6 +68,8 @@ export class MCPICloudflareAgent extends McpAgent {
     _autoDetectedOrigin; // Auto-detected server origin from request URL
     _clientMessagesConfig; // Client-specific delegation messages
     _clientProvidedSessionId; // Deprecated: Use KV mapping instead to avoid race conditions
+    _consentUIResourceUri; // MCP Apps consent UI resource URI (set if ext-apps available)
+    _vaultResolver; // Lazy-init: per-user API key vault resolver (VAULT-9)
     constructor(state, env, providerRegistry = defaultProviderRegistry) {
         // Call super() with just state and env (agents@0.2.21+ only accepts 2 parameters)
         // The config is no longer passed to the constructor - it's set via the server property
@@ -89,6 +94,11 @@ export class MCPICloudflareAgent extends McpAgent {
         mappedEnv._durableObjectState = state;
         // Load runtime configuration from subclass
         const runtimeConfig = this.getRuntimeConfigInternal(mappedEnv);
+        // Allow MCPI_INLINE_CONSENT env var to override the config flag
+        if (mappedEnv.MCPI_INLINE_CONSENT === "true" ||
+            mappedEnv.MCPI_INLINE_CONSENT === "1") {
+            runtimeConfig.inlineConsent = true;
+        }
         // Store environment for logging checks
         this._environment = runtimeConfig.environment || "production";
         // Create tool protection service if configured
@@ -166,6 +176,16 @@ export class MCPICloudflareAgent extends McpAgent {
             const clientInfo = params?.clientInfo;
             const protocolVersion = params?.protocolVersion;
             const capabilities = params?.capabilities;
+            // Log raw capabilities from client for debugging ext-apps support
+            console.error("[MCPICloudflareAgent] Client initialize capabilities:", {
+                clientName: clientInfo?.name,
+                protocolVersion,
+                hasCapabilities: !!capabilities,
+                capabilityKeys: capabilities ? Object.keys(capabilities) : [],
+                hasExtensions: !!capabilities?.extensions,
+                extensionKeys: capabilities?.extensions ? Object.keys(capabilities.extensions) : [],
+                rawCapabilities: JSON.stringify(capabilities)?.substring(0, 500),
+            });
             // Store client info for later retrieval (always, not just in dev)
             if (clientInfo || protocolVersion) {
                 await this.ctx.storage.put("mcpClientInfo", {
@@ -247,7 +267,7 @@ export class MCPICloudflareAgent extends McpAgent {
         const rawKeyPair = await cryptoProvider.generateKeyPair();
         // Generate proper did:key from Ed25519 public key
         const userDid = generateDidKeyFromBase64(rawKeyPair.publicKey);
-        const keyId = `${userDid}#keys-1`;
+        const keyId = `${userDid}#${didKeyFragment(userDid)}`;
         const keyPair = {
             did: userDid,
             publicKey: rawKeyPair.publicKey,
@@ -500,6 +520,9 @@ export class MCPICloudflareAgent extends McpAgent {
             if (!this.server) {
                 throw new Error("Server not initialized. This should not happen - server is initialized in constructor.");
             }
+            // Register MCP Apps consent UI resource BEFORE tools
+            // so that registerToolWithProof can add _meta.ui to tool definitions
+            await this.registerConsentUIResource();
             // Register tools (implemented by subclasses)
             await this.registerTools();
         }
@@ -508,6 +531,492 @@ export class MCPICloudflareAgent extends McpAgent {
             throw error;
         }
     }
+    /**
+     * Register the MCP Apps consent UI resource.
+     *
+     * Uses the existing <mcp-consent> Lit components bundled into a
+     * self-contained HTML string. The resource is served via standard
+     * MCP resources/read -- hosts that support MCP Apps will render it
+     * in a sandboxed iframe when a tool requires delegation.
+     *
+     * Gracefully no-ops when @modelcontextprotocol/ext-apps or
+     * @kya-os/consent/mcp-app are not available.
+     */
+    async registerConsentUIResource() {
+        try {
+            // Dynamic imports to handle optional peer dependencies
+            const [extApps, consentMcpApp, extAppsConstants] = await Promise.all([
+                import("@modelcontextprotocol/ext-apps/server").catch(() => null),
+                import("@kya-os/consent/mcp-app").catch(() => null),
+                import("@kya-os/mcp-i-core/runtime/ext-apps-constants").catch(() => null),
+            ]);
+            if (!extApps || !consentMcpApp || !extAppsConstants) {
+                logger.info("[MCPICloudflareAgent] MCP Apps consent UI not available (missing optional dependencies)");
+                return;
+            }
+            const { registerAppResource, RESOURCE_MIME_TYPE } = extApps;
+            // consentMcpApp imported for future full Lit-based UI; inline HTML used for now
+            const { CONSENT_UI_RESOURCE_URI } = extAppsConstants;
+            // Determine server URL for CSP connect-src
+            const serverUrl = this.env.MCP_SERVER_URL ??
+                this._autoDetectedOrigin;
+            const connectDomains = ["*.kya.vouched.id"];
+            if (serverUrl) {
+                try {
+                    connectDomains.push(new URL(serverUrl).hostname);
+                }
+                catch {
+                    // Invalid URL, skip
+                }
+            }
+            registerAppResource(this.server, "MCPI Consent", CONSENT_UI_RESOURCE_URI, {
+                description: "Authorization consent form for protected tools",
+                _meta: {
+                    ui: {
+                        csp: {
+                            connectDomains,
+                        },
+                    },
+                },
+            }, async () => {
+                // Use minimal inline handshake HTML while debugging LIT bundle issues.
+                // The full CONSENT_MCP_APP_HTML (628KB) loads but doesn't render —
+                // likely a CSP or sandboxed iframe restriction on the LIT bundle.
+                // This minimal version proves the data pipeline works end-to-end.
+                const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="color-scheme" content="light dark">
+  <title>MCPI Consent</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: system-ui, -apple-system, sans-serif; padding: 16px; background: transparent; }
+    .card { border-radius: 12px; padding: 20px; border: 1px solid rgba(128,128,128,0.2); }
+    h2 { font-size: 16px; font-weight: 600; margin-bottom: 8px; }
+    p { font-size: 13px; opacity: 0.7; line-height: 1.5; margin-bottom: 6px; }
+    .scopes { margin: 10px 0; }
+    .scope { display: inline-block; padding: 3px 10px; border-radius: 10px; font-size: 12px; font-weight: 500; margin: 2px 4px 2px 0; background: rgba(46,125,50,0.1); color: #2e7d32; }
+    .btn { display: inline-block; padding: 8px 20px; border-radius: 8px; border: none; font-size: 14px; font-weight: 500; cursor: pointer; margin-right: 8px; margin-top: 10px; }
+    .btn-approve { background: #2563eb; color: #fff; }
+    .btn-approve:disabled { opacity: 0.5; cursor: not-allowed; }
+    .btn-deny { background: transparent; border: 1px solid rgba(128,128,128,0.3); }
+    .info { font-size: 11px; opacity: 0.5; margin-top: 12px; }
+    .fallback { font-size: 12px; margin-top: 8px; }
+    .fallback a { color: #2563eb; }
+    #loading { font-size: 13px; opacity: 0.6; }
+    #consent { display: none; }
+    #approved { display: none; font-size: 14px; color: #16a34a; font-weight: 500; }
+    .cred-fields { display: none; margin: 12px 0; }
+    .cred-fields label { display: block; font-size: 12px; font-weight: 500; margin-bottom: 4px; opacity: 0.8; }
+    .cred-fields input[type="text"],
+    .cred-fields input[type="password"] { width: 100%; padding: 8px 10px; border-radius: 6px; border: 1px solid rgba(128,128,128,0.3); font-size: 14px; margin-bottom: 10px; background: transparent; color: inherit; }
+    .cred-fields input:focus { outline: none; border-color: #2563eb; }
+    .pw-wrap { position: relative; }
+    .pw-toggle { position: absolute; right: 8px; top: 8px; background: none; border: none; cursor: pointer; font-size: 13px; opacity: 0.5; color: inherit; }
+    .terms-row { display: flex; align-items: flex-start; gap: 8px; margin: 10px 0 4px; }
+    .terms-row input[type="checkbox"] { margin-top: 2px; }
+    .terms-row label { font-size: 12px; opacity: 0.7; cursor: pointer; }
+    .auth-error { display: none; font-size: 13px; color: #dc2626; margin: 8px 0; padding: 8px 10px; border-radius: 6px; background: rgba(220,38,38,0.08); }
+  </style>
+</head>
+<body>
+  <div id="loading">Waiting for consent data&hellip;</div>
+  <div id="consent" class="card">
+    <h2>Authorization Required</h2>
+    <p id="tool-desc"></p>
+    <div id="scopes-container" class="scopes"></div>
+    <div id="cred-fields" class="cred-fields">
+      <label for="cred-username">Username / Email</label>
+      <input type="text" id="cred-username" autocomplete="username" placeholder="Enter your username or email">
+      <label for="cred-password">Password</label>
+      <div class="pw-wrap">
+        <input type="password" id="cred-password" autocomplete="current-password" placeholder="Enter your password">
+        <button type="button" class="pw-toggle" id="pw-toggle" aria-label="Toggle password visibility">Show</button>
+      </div>
+    </div>
+    <div id="auth-error" class="auth-error"></div>
+    <div id="terms-row" class="terms-row" style="display:none;">
+      <input type="checkbox" id="terms-check">
+      <label for="terms-check">I agree to authorize this tool and accept the terms of service</label>
+    </div>
+    <p id="agent-info" class="info"></p>
+    <div>
+      <button class="btn btn-approve" id="approve-btn">Approve</button>
+      <button class="btn btn-deny" id="deny-btn">Deny</button>
+    </div>
+    <div class="fallback" id="fallback"></div>
+  </div>
+  <div id="approved"></div>
+  <script>
+    (function() {
+      var send = function(msg) { window.parent.postMessage(msg, "*"); };
+      var consentData = null;
+      var authMode = "consent-only";
+
+      function resizeNotify() {
+        send({ jsonrpc: "2.0", method: "ui/notifications/size-changed", params: {
+          width: document.documentElement.scrollWidth,
+          height: document.documentElement.scrollHeight
+        }});
+      }
+
+      function showConsent(data) {
+        consentData = data;
+        authMode = data.authMode || "consent-only";
+        document.getElementById("loading").style.display = "none";
+        document.getElementById("consent").style.display = "block";
+
+        if (authMode === "credentials") {
+          document.getElementById("tool-desc").textContent =
+            "Tool \u201c" + (data.tool || "unknown") + "\u201d requires authentication.";
+          document.getElementById("cred-fields").style.display = "block";
+          document.getElementById("terms-row").style.display = "flex";
+          document.getElementById("approve-btn").textContent = "Sign In & Authorize";
+          document.getElementById("approve-btn").disabled = true;
+          document.getElementById("terms-check").addEventListener("change", function() {
+            document.getElementById("approve-btn").disabled = !this.checked;
+          });
+        } else {
+          document.getElementById("tool-desc").textContent =
+            "Tool \u201c" + (data.tool || "unknown") + "\u201d requires your approval.";
+        }
+
+        var scopesEl = document.getElementById("scopes-container");
+        var scopes = data.scopes || [];
+        scopesEl.textContent = "";
+        scopes.forEach(function(s) {
+          var span = document.createElement("span");
+          span.className = "scope";
+          span.textContent = s;
+          scopesEl.appendChild(span);
+        });
+        document.getElementById("agent-info").textContent =
+          "Agent: " + (data.agentName || data.agentDid || "unknown");
+        if (data.consentUrl) {
+          var fallbackEl = document.getElementById("fallback");
+          fallbackEl.textContent = "";
+          var a = document.createElement("a");
+          a.href = data.consentUrl;
+          a.target = "_blank";
+          a.rel = "noopener";
+          a.textContent = "Open in browser";
+          fallbackEl.appendChild(a);
+        }
+        resizeNotify();
+      }
+
+      // Password visibility toggle
+      document.getElementById("pw-toggle").addEventListener("click", function() {
+        var pwInput = document.getElementById("cred-password");
+        if (pwInput.type === "password") {
+          pwInput.type = "text";
+          this.textContent = "Hide";
+        } else {
+          pwInput.type = "password";
+          this.textContent = "Show";
+        }
+      });
+
+      var pendingRequests = {};
+      var nextId = 100;
+
+      function handleApprovalResponse(result, error) {
+        var statusEl = document.getElementById("approved");
+        if (error) {
+          // Show error inline for credential mode (allow retry)
+          if (authMode === "credentials") {
+            var errEl = document.getElementById("auth-error");
+            errEl.textContent = error.message || JSON.stringify(error);
+            errEl.style.display = "block";
+            document.getElementById("consent").style.display = "block";
+            statusEl.style.display = "none";
+            document.getElementById("approve-btn").disabled = !document.getElementById("terms-check").checked;
+            resizeNotify();
+            return;
+          }
+          statusEl.textContent = "Approval error: " + (error.message || JSON.stringify(error));
+          statusEl.style.color = "#dc2626";
+        } else {
+          try {
+            var text = result && result.content && result.content[0] && result.content[0].text;
+            var respData = text ? JSON.parse(text) : {};
+            if (respData.success) {
+              statusEl.textContent = "Authorization granted. You can now retry the tool.";
+              statusEl.style.color = "#22c55e";
+            } else {
+              // For credential auth failures, show error inline and allow retry
+              if (authMode === "credentials" && (respData.error_code === "auth_failed" || respData.error_code === "validation_error")) {
+                var errEl = document.getElementById("auth-error");
+                errEl.textContent = respData.error || "Authentication failed. Please check your credentials.";
+                errEl.style.display = "block";
+                document.getElementById("consent").style.display = "block";
+                statusEl.style.display = "none";
+                document.getElementById("approve-btn").disabled = !document.getElementById("terms-check").checked;
+                resizeNotify();
+                return;
+              }
+              statusEl.textContent = "Approval error: " + (respData.error || respData.error_code || "Unknown");
+              statusEl.style.color = "#f59e0b";
+            }
+          } catch(e) {
+            statusEl.textContent = "Unexpected response";
+            statusEl.style.color = "#f59e0b";
+          }
+        }
+        resizeNotify();
+      }
+
+      document.getElementById("approve-btn").addEventListener("click", function() {
+        if (!consentData) return;
+        // Hide any previous error
+        document.getElementById("auth-error").style.display = "none";
+        var statusEl = document.getElementById("approved");
+        document.getElementById("consent").style.display = "none";
+        statusEl.style.display = "block";
+        statusEl.textContent = authMode === "credentials" ? "Authenticating..." : "Sending approval...";
+        statusEl.style.color = "";
+        // Use tools/call via postMessage (proxied through host to MCP server)
+        // instead of fetch() which is blocked in the sandboxed iframe.
+        var reqId = nextId++;
+        pendingRequests[reqId] = handleApprovalResponse;
+
+        if (authMode === "credentials") {
+          var username = document.getElementById("cred-username").value;
+          var password = document.getElementById("cred-password").value;
+          if (!username || !password) {
+            statusEl.style.display = "none";
+            document.getElementById("consent").style.display = "block";
+            var errEl = document.getElementById("auth-error");
+            errEl.textContent = "Please enter both username and password.";
+            errEl.style.display = "block";
+            resizeNotify();
+            return;
+          }
+          send({
+            jsonrpc: "2.0", id: reqId, method: "tools/call",
+            params: {
+              name: "_mcpi_credential_auth",
+              arguments: {
+                tool: consentData.tool,
+                scopes: consentData.scopes,
+                session_id: consentData.sessionId,
+                agent_did: consentData.agentDid,
+                project_id: consentData.projectId,
+                resume_token: consentData.resumeToken,
+                username: username,
+                password: password,
+                provider: consentData.provider || "credentials"
+              }
+            }
+          });
+        } else {
+          send({
+            jsonrpc: "2.0", id: reqId, method: "tools/call",
+            params: {
+              name: "_mcpi_approve_consent",
+              arguments: {
+                tool: consentData.tool,
+                scopes: consentData.scopes,
+                session_id: consentData.sessionId,
+                agent_did: consentData.agentDid,
+                project_id: consentData.projectId,
+                resume_token: consentData.resumeToken
+              }
+            }
+          });
+        }
+        resizeNotify();
+      });
+
+      document.getElementById("deny-btn").addEventListener("click", function() {
+        document.getElementById("consent").style.display = "none";
+        document.getElementById("approved").style.display = "block";
+        document.getElementById("approved").textContent = "Authorization denied.";
+        document.getElementById("approved").style.color = "#dc2626";
+        resizeNotify();
+      });
+
+      window.addEventListener("message", function(e) {
+        if (e.source !== window.parent) return;
+        var msg = e.data;
+        if (!msg || msg.jsonrpc !== "2.0") return;
+
+        if (msg.id === 0 && msg.result) {
+          var ctx = msg.result.hostContext || {};
+          if (ctx.theme === "dark") document.documentElement.style.colorScheme = "dark";
+          send({ jsonrpc: "2.0", method: "ui/notifications/initialized" });
+          resizeNotify();
+        }
+        // Handle responses to our pending tools/call requests
+        if (msg.id != null && pendingRequests[msg.id]) {
+          pendingRequests[msg.id](msg.result, msg.error);
+          delete pendingRequests[msg.id];
+        }
+        if (msg.method === "ui/notifications/tool-result" && msg.params) {
+          var sc = msg.params.structuredContent;
+          if (sc && sc.type === "consent_required") showConsent(sc);
+        }
+        if (msg.method === "ui/notifications/tool-input" && msg.params) {
+          var args = msg.params.arguments;
+          if (args && args.type === "consent_required") showConsent(args);
+        }
+        if (msg.method === "ping" && msg.id != null) {
+          send({ jsonrpc: "2.0", id: msg.id, result: {} });
+        }
+        if (msg.method === "ui/resource-teardown" && msg.id != null) {
+          send({ jsonrpc: "2.0", id: msg.id, result: {} });
+        }
+      });
+
+      send({
+        jsonrpc: "2.0", id: 0, method: "ui/initialize",
+        params: {
+          appInfo: { name: "MCPI Consent", version: "1.0.0" },
+          appCapabilities: {},
+          protocolVersion: "2026-01-26"
+        }
+      });
+    })();
+  </script>
+</body>
+</html>`;
+                return {
+                    contents: [
+                        {
+                            uri: CONSENT_UI_RESOURCE_URI,
+                            mimeType: RESOURCE_MIME_TYPE,
+                            text: html,
+                        },
+                    ],
+                };
+            });
+            // Store the resource URI so registerToolWithProof can add _meta.ui to tool definitions
+            this._consentUIResourceUri = CONSENT_UI_RESOURCE_URI;
+            // Signal to MCPIRuntimeBase that ext-apps is available.
+            // The base class's isExtAppsAvailable() uses synchronous require() which
+            // fails for ESM-only packages in CJS/Workers contexts. This cached flag
+            // ensures buildConsentUIResult() works correctly at tool-call time.
+            this.mcpiRuntime?.setExtAppsAvailable(true);
+            // Register internal tool for iframe-based consent approval.
+            // The sandboxed MCP Apps iframe cannot call fetch() directly, so it
+            // uses tools/call (proxied via postMessage through the host) to invoke
+            // this tool which handles the /consent/approve logic server-side.
+            this.server.tool("_mcpi_approve_consent", "DO NOT call this tool directly. Internal system tool used by the consent UI iframe to process approval actions. Only the embedded consent form should invoke this.", {
+                tool: z.string(),
+                scopes: z.array(z.string()),
+                session_id: z.string(),
+                agent_did: z.string(),
+                project_id: z.string(),
+                resume_token: z.string(),
+            }, async (args) => {
+                const envPrefix = this.getEnvPrefix();
+                const mappedEnv = envPrefix
+                    ? mapPrefixedEnv(this.env, envPrefix)
+                    : this.env;
+                const serverUrl = mappedEnv.MCP_SERVER_URL ??
+                    this._autoDetectedOrigin;
+                if (!serverUrl) {
+                    return { content: [{ type: "text", text: JSON.stringify({ success: false, error: "No server URL configured" }) }] };
+                }
+                try {
+                    const resp = await fetch(`${serverUrl}/consent/approve`, {
+                        method: "POST",
+                        headers: { "Content-Type": "application/json" },
+                        body: JSON.stringify({
+                            tool: args.tool,
+                            scopes: args.scopes,
+                            session_id: args.session_id,
+                            agent_did: args.agent_did,
+                            project_id: args.project_id,
+                            resume_token: args.resume_token,
+                            termsAccepted: true,
+                            approved: true,
+                        }),
+                    });
+                    if (!resp.ok) {
+                        return { content: [{ type: "text", text: JSON.stringify({ success: false, error: `Server error: ${resp.status}` }) }] };
+                    }
+                    const data = await resp.json();
+                    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : "Unknown error";
+                    return { content: [{ type: "text", text: JSON.stringify({ success: false, error: msg }) }] };
+                }
+            });
+            // Register internal tool for iframe-based credential authentication.
+            // Same sandbox workaround as _mcpi_approve_consent: the iframe calls
+            // tools/call via postMessage, which the host proxies to this tool.
+            // This tool does credential auth + delegation in a single step.
+            this.server.tool("_mcpi_credential_auth", "DO NOT call this tool directly. Internal system tool used by the consent UI iframe to process credential authentication. Only the embedded consent form should invoke this.", {
+                tool: z.string(),
+                scopes: z.array(z.string()),
+                session_id: z.string(),
+                agent_did: z.string(),
+                project_id: z.string(),
+                resume_token: z.string(),
+                username: z.string(),
+                password: z.string(),
+                provider: z.string(),
+            }, async (args) => {
+                const envPrefix = this.getEnvPrefix();
+                const mappedEnv = envPrefix
+                    ? mapPrefixedEnv(this.env, envPrefix)
+                    : this.env;
+                const serverUrl = mappedEnv.MCP_SERVER_URL ??
+                    this._autoDetectedOrigin;
+                if (!serverUrl) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: false,
+                                    error: "No server URL configured",
+                                }),
+                            },
+                        ],
+                    };
+                }
+                try {
+                    const resp = await fetch(`${serverUrl}/consent/approve`, {
+                        method: "POST",
+                        headers: { "Content-Type": "application/json" },
+                        body: JSON.stringify({
+                            tool: args.tool,
+                            scopes: args.scopes,
+                            session_id: args.session_id,
+                            agent_did: args.agent_did,
+                            project_id: args.project_id,
+                            provider_type: "password",
+                            provider: args.provider,
+                            username: args.username,
+                            password: args.password,
+                            inline_mode: true,
+                            termsAccepted: true,
+                            approved: true,
+                        }),
+                    });
+                    if (!resp.ok) {
+                        return { content: [{ type: "text", text: JSON.stringify({ success: false, error: `Server error: ${resp.status}` }) }] };
+                    }
+                    const data = await resp.json();
+                    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : "Unknown error";
+                    return { content: [{ type: "text", text: JSON.stringify({ success: false, error: msg }) }] };
+                }
+            });
+            logger.info("[MCPICloudflareAgent] Registered MCP Apps consent UI resource");
+        }
+        catch {
+            // ext-apps or consent/mcp-app not available - graceful no-op
+            logger.info("[MCPICloudflareAgent] MCP Apps consent UI not available (ext-apps or consent/mcp-app not installed)");
+        }
+    }
     /**
      * Register a tool with automatic session ID extraction and proof generation
      *
@@ -602,14 +1111,32 @@ export class MCPICloudflareAgent extends McpAgent {
                     zodSchemaShape = schema;
                 }
             }
-            this.server.tool(name, description, zodSchemaShape, async (args, extra) => {
+            // Use registerTool (not deprecated server.tool) to support _meta.ui for MCP Apps
+            const toolCallback = async (args, extra) => {
                 // ✅ Automatically extract sessionId from ToolExtraArguments
                 // This ensures delegation tokens stored with the original session ID
                 // can be retrieved on subsequent tool calls
-                // Note: extra is typed as 'any' to match MCP SDK's ToolExtraArguments type
                 const sessionId = extra?.sessionId;
                 return this.executeToolWithProof(name, args, handler, sessionId);
-            });
+            };
+            // Build tool config with optional MCP Apps UI metadata
+            // When ext-apps consent UI is registered, include _meta.ui.resourceUri
+            // so clients know this tool can render inline consent UI
+            const toolConfig = {
+                description,
+                inputSchema: zodSchemaShape,
+            };
+            if (this._consentUIResourceUri) {
+                // Include BOTH new nested format AND legacy flat format for maximum client compatibility
+                // registerAppTool() from ext-apps SDK normalizes both; we replicate that here
+                // New format: _meta.ui.resourceUri  (preferred)
+                // Legacy format: _meta["ui/resourceUri"]  (deprecated but some clients may check this)
+                toolConfig._meta = {
+                    ui: { resourceUri: this._consentUIResourceUri },
+                    "ui/resourceUri": this._consentUIResourceUri,
+                };
+            }
+            this.server.registerTool(name, toolConfig, toolCallback);
         }
         catch (error) {
             logger.error(`[MCPICloudflareAgent] Failed to register tool "${name}":`, error);
@@ -857,6 +1384,7 @@ export class MCPICloudflareAgent extends McpAgent {
             createdAt: timestamp,
             expiresAt: timestamp + 30 * 60 * 1000, // 30 minutes
             serverOrigin: serverUrl, // Use MCP_SERVER_URL for consent URL building
+            projectId: mappedEnv.AGENTSHIELD_PROJECT_ID || "", // For inline consent UI approve POST
             delegationToken, // ✅ Include token in session if found
             delegationId, // ✅ Include delegationId for proof submission attribution
             userDid, // ✅ FIX: Include userDid in session for ToolExecutionContext propagation
@@ -883,6 +1411,10 @@ export class MCPICloudflareAgent extends McpAgent {
         // ✅ SECURITY FIX: Store original auth error to re-throw if URL building fails
         // This prevents unauthorized tool execution when URL building fails
         let originalAuthError = null;
+        // ✅ MCP Apps inline UI result for credential auth (returns UI instead of throwing)
+        let pendingInlineResult = null;
+        // Store AuthRequiredError to throw inside the inner try block where its handler lives
+        let pendingAuthRequiredError = null;
         try {
             toolContext = await this.buildToolContext(toolName, userDid, sessionId, delegationToken, mappedEnv);
         }
@@ -901,17 +1433,31 @@ export class MCPICloudflareAgent extends McpAgent {
                     const scopes = credError.toolProtection?.requiredScopes || [
                         `${toolName}:execute`,
                     ];
-                    // Build consent page URL with credentials mode
-                    const consentUrl = await this.buildConsentUrlForCredentials(toolName, provider, scopes, sessionId, mappedEnv);
                     const resumeToken = `resume_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
-                    logger.info("[MCPICloudflareAgent] 🔑 Credential auth required:", {
-                        tool: toolName,
-                        provider,
-                        scopes,
-                        consentUrl: consentUrl.substring(0, 80) + "...",
-                    });
-                    // ✅ FIX: Store error instead of throwing to ensure proper formatting
-                    pendingAuthError = new DelegationRequiredError(toolName, scopes, consentUrl, undefined, resumeToken);
+                    // Try MCP Apps inline credential UI first (preferred path)
+                    // Note: clientCapabilities not available in this context — pass undefined.
+                    // buildConsentUIResult gates on isExtAppsAvailable(), not client caps.
+                    const inlineResult = this.mcpiRuntime.buildConsentUIResult(toolName, scopes, session, resumeToken, session.projectId, session.serverOrigin, undefined, "credentials", provider);
+                    if (inlineResult) {
+                        logger.info("[MCPICloudflareAgent] 🔑 Credential auth required (inline UI):", {
+                            tool: toolName,
+                            provider,
+                            scopes,
+                        });
+                        pendingInlineResult = inlineResult;
+                    }
+                    else {
+                        // ext-apps not available — fall back to external consent URL
+                        const consentUrl = await this.buildConsentUrlForCredentials(toolName, provider, scopes, sessionId, mappedEnv);
+                        logger.info("[MCPICloudflareAgent] 🔑 Credential auth required:", {
+                            tool: toolName,
+                            provider,
+                            scopes,
+                            consentUrl: consentUrl.substring(0, 80) + "...",
+                        });
+                        // ✅ FIX: Store error instead of throwing to ensure proper formatting
+                        pendingAuthError = new DelegationRequiredError(toolName, scopes, consentUrl, undefined, resumeToken);
+                    }
                 }
                 catch (credentialError) {
                     // If URL building fails, log the error but continue
@@ -982,25 +1528,37 @@ export class MCPICloudflareAgent extends McpAgent {
                         isCredentialProvider,
                     });
                     let authUrl;
+                    const resumeToken = `resume_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
                     if (isCredentialProvider) {
-                        // For credential/password providers, build consent URL pointing to credential form
-                        logger.info("[MCPICloudflareAgent] 🔑 Credential auth required (from OAuthRequiredError):", {
-                            tool: oauthError.toolName,
-                            provider: oauthError.provider,
-                            scopes: oauthError.requiredScopes,
-                        });
-                        authUrl = await this.buildConsentUrlForCredentials(oauthError.toolName, oauthError.provider || "credentials", oauthError.requiredScopes, sessionId, mappedEnv);
+                        // Try MCP Apps inline credential UI first
+                        const inlineResult = this.mcpiRuntime?.buildConsentUIResult(oauthError.toolName, oauthError.requiredScopes, session, resumeToken, session.projectId, session.serverOrigin, undefined, "credentials", oauthError.provider || "credentials");
+                        if (inlineResult) {
+                            logger.info("[MCPICloudflareAgent] 🔑 Credential auth required (inline UI from OAuthRequiredError):", {
+                                tool: oauthError.toolName,
+                                provider: oauthError.provider,
+                                scopes: oauthError.requiredScopes,
+                            });
+                            pendingInlineResult = inlineResult;
+                        }
+                        else {
+                            // ext-apps not available — fall back to external consent URL
+                            logger.info("[MCPICloudflareAgent] 🔑 Credential auth required (from OAuthRequiredError):", {
+                                tool: oauthError.toolName,
+                                provider: oauthError.provider,
+                                scopes: oauthError.requiredScopes,
+                            });
+                            authUrl = await this.buildConsentUrlForCredentials(oauthError.toolName, oauthError.provider || "credentials", oauthError.requiredScopes, sessionId, mappedEnv);
+                        }
                     }
                     else {
                         // For OAuth providers (github, google, etc.), build OAuth URL
                         authUrl = await this.buildOAuthUrlForError(oauthError, sessionId, mappedEnv);
                     }
-                    // Generate resume token using runtime's internal method
-                    // The runtime will generate it when DelegationRequiredError is thrown
-                    const resumeToken = `resume_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
-                    // ✅ FIX: Store error instead of throwing to ensure proper formatting
-                    pendingAuthError = new DelegationRequiredError(oauthError.toolName, oauthError.requiredScopes, authUrl, undefined, // interceptedCall
-                    resumeToken);
+                    // Only create DelegationRequiredError if we didn't get an inline result
+                    if (!pendingInlineResult) {
+                        pendingAuthError = new DelegationRequiredError(oauthError.toolName, oauthError.requiredScopes, authUrl, undefined, // interceptedCall
+                        resumeToken);
+                    }
                 }
                 catch (oauthError) {
                     // If URL building fails, log the error
@@ -1012,10 +1570,18 @@ export class MCPICloudflareAgent extends McpAgent {
                     }
                 }
             }
+            // Store AuthRequiredError to throw inside the inner try block
+            // where the handler can catch it and return a structured MCP response.
+            if (error instanceof Error &&
+                (error.name === "AuthRequiredError" ||
+                    error.constructor?.name === "AuthRequiredError")) {
+                pendingAuthRequiredError = error;
+            }
             // ✅ SECURITY FIX: If we had an auth error but URL building failed,
             // we MUST re-throw the original error to prevent unauthorized tool execution.
             // Only log and continue for non-auth errors (backward compatibility).
-            if (!pendingAuthError) {
+            // Note: pendingInlineResult means auth is handled via inline UI — skip re-throw.
+            if (!pendingAuthError && !pendingInlineResult && !pendingAuthRequiredError) {
                 if (originalAuthError) {
                     // Auth was required but URL building failed - MUST block execution
                     logger.error("[MCPICloudflareAgent] SECURITY: Auth required but URL building failed, blocking tool execution:", { originalError: originalAuthError.message, buildError: error });
@@ -1050,13 +1616,20 @@ export class MCPICloudflareAgent extends McpAgent {
             }
         };
         // Execute tool with automatic proof generation
+        // If inline credential UI was prepared, return it directly (no error throw needed)
+        if (pendingInlineResult) {
+            return pendingInlineResult;
+        }
         // Wrap in try-catch to handle DelegationRequiredError and format for MCP clients
         try {
-            // ✅ FIX: Throw pendingAuthError INSIDE the try block
-            // This ensures it's caught by the DelegationRequiredError formatter below
+            // ✅ FIX: Throw pending errors INSIDE the try block
+            // This ensures they're caught by the formatters below
             if (pendingAuthError) {
                 throw pendingAuthError;
             }
+            if (pendingAuthRequiredError) {
+                throw pendingAuthRequiredError;
+            }
             const result = await this.mcpiRuntime.processToolCall(toolName, args, handlerWithContext, session);
             // NOTE: Proof submission is now awaited directly in CloudflareRuntime.processToolCall()
             // This ensures reliable submission without relying on ctx.waitUntil() which is unreliable
@@ -1088,14 +1661,18 @@ export class MCPICloudflareAgent extends McpAgent {
                 // Use DelegationErrorFormatter for consistent message formatting
                 // Supports client-specific messages via getClientMessagesConfig()
                 const formatter = new DelegationErrorFormatter(this.getClientMessagesConfig());
-                const { message: displayMessage } = formatter.format({
+                const { message: displayMessage, consentUrl } = formatter.format({
                     toolName: toolNameForError,
                     consentUrl: delegationError.consentUrl,
                     scopes,
                     clientId,
                 });
-                // Return tool result with isError: true (MCP standard for user-visible errors)
-                // This format is what Claude Desktop and MCP Inspector display to users
+                // Return tool result with isError: true so MCP clients (Claude Desktop, Inspector)
+                // surface the consent URL to users and trigger browser popup for authorization.
+                // TODO(ext-apps): When MCP-UI / ext-apps support lands, make this dynamic:
+                //   - isError: false when the client supports inline consent UI (MCP Apps extension)
+                //   - isError: true as fallback for standard MCP clients (Claude Desktop, etc.)
+                //   See PR #274 for the inline consent UI implementation.
                 return {
                     content: [
                         {
@@ -1104,6 +1681,14 @@ export class MCPICloudflareAgent extends McpAgent {
                         },
                     ],
                     isError: true,
+                    _meta: {
+                        errorType: "authorization_required",
+                        toolName: toolNameForError,
+                        requiredScopes: scopes,
+                        consentUrl,
+                        authorizationUrl: consentUrl,
+                        resumeToken,
+                    },
                 };
             }
             // Handle OAuthRequiredError - use formatOAuth() to preserve provider name
@@ -1131,7 +1716,7 @@ export class MCPICloudflareAgent extends McpAgent {
                 // Use DelegationErrorFormatter.formatOAuth() for OAuth-specific message
                 // This preserves the provider name (e.g., "Sign in with GitHub")
                 const formatter = new DelegationErrorFormatter(this.getClientMessagesConfig());
-                const { message: displayMessage } = formatter.formatOAuth({
+                const { message: displayMessage, oauthUrl } = formatter.formatOAuth({
                     toolName: toolNameForError,
                     oauthUrl: oauthError.oauthUrl,
                     provider,
@@ -1146,6 +1731,43 @@ export class MCPICloudflareAgent extends McpAgent {
                         },
                     ],
                     isError: true,
+                    _meta: {
+                        errorType: "oauth_required",
+                        toolName: toolNameForError,
+                        provider,
+                        requiredScopes: scopes,
+                        oauthUrl,
+                        authorizationUrl: oauthUrl,
+                        resumeToken: oauthError.resumeToken,
+                    },
+                };
+            }
+            // Handle AuthRequiredError - return machine-readable error with configUrl
+            // MCP clients use this to show "Add your API key" with a link to the dashboard
+            if (error instanceof Error &&
+                (error.name === "AuthRequiredError" ||
+                    error.constructor?.name === "AuthRequiredError")) {
+                const authError = error;
+                logger.info("[MCPICloudflareAgent] 🔑 Auth required (no vault + no static env):", {
+                    tool: toolName,
+                    type: authError.type,
+                    envVarNames: authError.envVarNames,
+                    configUrl: authError.configUrl,
+                });
+                // Return both human-readable text AND machine-readable JSON
+                // so MCP clients can parse the structured error or display the message
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: authError.message,
+                        },
+                        {
+                            type: "text",
+                            text: JSON.stringify(authError.toJSON()),
+                        },
+                    ],
+                    isError: true,
                 };
             }
             // Re-throw other errors to be handled by MCP SDK
@@ -1158,8 +1780,9 @@ export class MCPICloudflareAgent extends McpAgent {
      * @private
      */
     async buildToolContext(toolName, userDid, sessionId, delegationToken, env) {
-        // Only build context if userDid is available and services are configured
-        if (!userDid || !env.AGENTSHIELD_API_KEY || !env.DELEGATION_STORAGE) {
+        // Only build context if userDid is available and AgentShield API is configured.
+        // Note: DELEGATION_STORAGE is only required for password/OAuth paths, not apikey vault.
+        if (!userDid || !env.AGENTSHIELD_API_KEY) {
             return undefined;
         }
         // Check if tool protection service is available
@@ -1182,6 +1805,10 @@ export class MCPICloudflareAgent extends McpAgent {
             const isPasswordAuth = protection.authorization?.type === "password" ||
                 protection.oauthProvider === "credentials"; // Deprecated fallback
             if (isPasswordAuth) {
+                if (!env.DELEGATION_STORAGE) {
+                    logger.warn("[MCPICloudflareAgent] Password auth requires DELEGATION_STORAGE but it is not configured");
+                    return undefined;
+                }
                 const provider = protection.authorization?.type === "password"
                     ? protection.authorization.provider
                     : "credentials";
@@ -1302,6 +1929,110 @@ export class MCPICloudflareAgent extends McpAgent {
                     return undefined;
                 }
             }
+            // For API key vault tools, resolve per-user secrets from AgentShield vault.
+            // This follows the same early-return pattern as isPasswordAuth above.
+            if (hasApiKeyAuthorization(protection)) {
+                const projectId = toolProtectionService.getProjectId();
+                if (!projectId) {
+                    return undefined;
+                }
+                const { envVarNames, headerMapping } = protection.authorization;
+                try {
+                    // Lazy-init VaultResolver as class-level singleton so its per-session
+                    // cache persists across tool calls within the same DO instance.
+                    if (!this._vaultResolver) {
+                        const identity = await this.mcpiRuntime.getIdentity();
+                        // Decode base64/base64url private key to bytes (self-contained, no private method access)
+                        const b64 = identity.privateKey.replace(/-/g, "+").replace(/_/g, "/");
+                        const padded = b64 + "=".repeat((4 - (b64.length % 4)) % 4);
+                        const binaryStr = atob(padded);
+                        const keyBytes = new Uint8Array(binaryStr.length);
+                        for (let i = 0; i < binaryStr.length; i++)
+                            keyBytes[i] = binaryStr.charCodeAt(i);
+                        // Detect key format and extract raw 32-byte Ed25519 key:
+                        // - PKCS#8 (48 bytes, 0x30 prefix): extract raw key at offset 16
+                        // - Raw 64-byte (seed+pub): take first 32
+                        // - Raw 32-byte: use as-is
+                        const rawKey = keyBytes.length === 48 && keyBytes[0] === 0x30
+                            ? keyBytes.slice(16, 48)
+                            : keyBytes.length === 64
+                                ? keyBytes.slice(0, 32)
+                                : keyBytes;
+                        // Wrap as PKCS#8 for crypto.subtle.importKey
+                        const pkcs8Header = new Uint8Array([
+                            0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05,
+                            0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
+                        ]);
+                        const pkcs8 = new Uint8Array(pkcs8Header.length + rawKey.length);
+                        pkcs8.set(pkcs8Header);
+                        pkcs8.set(rawKey, pkcs8Header.length);
+                        const identityKey = await crypto.subtle.importKey("pkcs8", pkcs8.buffer, { name: "Ed25519", namedCurve: "Ed25519" }, false, ["sign"]);
+                        this._vaultResolver = new VaultResolver({
+                            apiUrl: env.AGENTSHIELD_API_URL || "https://kya.vouched.id",
+                            apiKey: env.AGENTSHIELD_API_KEY,
+                            identityKey,
+                            agentDid: identity.did,
+                        });
+                    }
+                    const secrets = await this._vaultResolver.resolve(projectId, userDid, toolName, envVarNames, sessionId || "ephemeral");
+                    // Build idpHeaders from generic headerMapping (not hardcoded header names)
+                    const idpHeaders = {};
+                    for (const [envVar, headerName] of Object.entries(headerMapping)) {
+                        if (secrets[envVar]) {
+                            idpHeaders[headerName] = secrets[envVar];
+                        }
+                    }
+                    // If vault returned no usable secrets, check static env fallback.
+                    // If static env also lacks the required vars, throw a machine-readable
+                    // AuthRequiredError so MCP clients can present actionable guidance.
+                    if (Object.keys(idpHeaders).length === 0) {
+                        const hasStaticFallback = envVarNames.every((name) => !!env[name]);
+                        if (hasStaticFallback) {
+                            if (this._environment === "development") {
+                                logger.debug("[MCPICloudflareAgent] Vault returned no secrets, falling back to static env:", { tool: toolName, userDid: userDid?.slice(0, 20) + "..." });
+                            }
+                            return undefined;
+                        }
+                        // No vault secrets AND no static env — throw structured error
+                        const apiUrl = env.AGENTSHIELD_API_URL || "https://kya.vouched.id";
+                        // Use /dashboard/projects/{id} path — works without orgId and
+                        // the dashboard redirects to the correct org-scoped route.
+                        const configUrl = `${apiUrl}/dashboard/projects/${projectId}/settings`;
+                        throw new AuthRequiredError({
+                            type: "apikey",
+                            envVarNames,
+                            configUrl,
+                            message: `API key required: configure ${envVarNames.join(", ")} in your project settings. ` +
+                                `Visit ${configUrl} to add your keys.`,
+                        });
+                    }
+                    if (this._environment === "development") {
+                        logger.debug("[MCPICloudflareAgent] Vault context built for apikey auth:", {
+                            tool: toolName,
+                            resolvedKeys: Object.keys(idpHeaders),
+                            userDid: userDid?.slice(0, 20) + "...",
+                        });
+                    }
+                    return {
+                        idpHeaders,
+                        userDid,
+                        sessionId,
+                        provider: "vault",
+                    };
+                }
+                catch (vaultError) {
+                    // Re-throw AuthRequiredError — it means vault AND static env are both empty.
+                    // Must propagate so the tool-call handler can return a structured response.
+                    if (vaultError instanceof Error &&
+                        (vaultError.name === "AuthRequiredError" ||
+                            vaultError.constructor?.name === "AuthRequiredError")) {
+                        throw vaultError;
+                    }
+                    logger.warn("[MCPICloudflareAgent] Vault resolution failed, falling through:", vaultError);
+                    // Fall through — tool may still work with static env secrets (Level 0)
+                    return undefined;
+                }
+            }
             // Get project ID from tool protection service
             const projectId = toolProtectionService.getProjectId();
             if (!projectId) {
@@ -1384,6 +2115,13 @@ export class MCPICloudflareAgent extends McpAgent {
             ) {
                 throw error;
             }
+            // Re-throw AuthRequiredError so it can be handled by executeToolWithProof
+            // This error indicates missing per-user auth with no static env fallback
+            if (error instanceof Error &&
+                (error.name === "AuthRequiredError" ||
+                    error.constructor?.name === "AuthRequiredError")) {
+                throw error;
+            }
             logger.warn("[MCPICloudflareAgent] Failed to build tool context:", error);
             return undefined;
         }
@@ -1927,6 +2665,20 @@ export class MCPICloudflareAgent extends McpAgent {
                 }), { status: 500, headers: { "Content-Type": "application/json" } });
             }
         }
+        // Handle internal client capabilities request
+        // Returns stored MCP client capabilities from the initialize message
+        if (url.pathname === "/_internal/client-capabilities" && request.method === "GET") {
+            try {
+                const mcpClientInfo = await this.getMcpClientInfo();
+                return new Response(JSON.stringify({
+                    success: true,
+                    capabilities: mcpClientInfo?.capabilities || null,
+                }), { status: 200, headers: { "Content-Type": "application/json" } });
+            }
+            catch (error) {
+                return new Response(JSON.stringify({ success: false, capabilities: null }), { status: 200, headers: { "Content-Type": "application/json" } });
+            }
+        }
         // Handle internal cache-clear request
         if (url.pathname === "/_do/cache-clear" && request.method === "POST") {
             logger.info("[MCPICloudflareAgent] Handling internal cache-clear request");