@topolo/mcp 0.12.0 → 0.13.0

package/README.md

@@ -24,16 +24,29 @@ Customers install only `@topolo/cli`; it owns an exact compatible MCP and SDK.
 `topolo setup` registers the resolved local Node entry point, so agent startup
 does not depend on `npx`, network access, or a separately synchronized package.
 
-## Get a credential
+## Register an accountable agent installation
 
-Either:
+For Codex, Claude, and other persistent agent hosts, register the host once
+from an organization context:
 
-- **Long-lived**: mint an API key at the Topolo Developers console
-  (`TOPOLO_API_KEY=topo_live_...`). Preferred for persistent agent installs.
-- **Short-lived**: run `topolo auth login`. The stdio MCP reads and refreshes
-  the same environment-specific credential store, so no token copying is
-  needed. Explicit `TOPOLO_API_KEY` or `TOPOLO_ACCESS_TOKEN` values still take
-  precedence for headless installations.
+```bash
+topolo installations register \
+  --name "Codex on my workstation" \
+  --provider openai \
+  --host codex \
+  --grant app_topolo_agent:actions
+```
+
+The CLI creates an accountable external principal, generates a device-local
+DPoP key, stores the client secret and private key in the operating system's
+protected credential store, and configures the host with only
+`TOPOLO_AGENT_INSTALLATION_ID`. The MCP exchanges short-lived credentials for
+the exact service, task, and resource being accessed. No reusable secret is
+written to Codex or Claude configuration.
+
+Human OAuth contexts and explicit API keys remain supported for interactive
+and compatibility use, but they are never used as a fallback when an
+installation ID is configured.
 
 ## Register with an MCP client
 
@@ -50,11 +63,13 @@ must not use an `npx` launcher because that makes startup network-dependent.
 | `TOPOLO_ACCESS_TOKEN`        | Short-lived JWT (dev/testing)                         |
 | `TOPOLO_ENV`                 | Credential environment (production by default)       |
 | `TOPOLO_CONTEXT`             | Pin one stored personal/org context without activating it |
+| `TOPOLO_AGENT_INSTALLATION_ID` | Use a protected accountable agent installation          |
+| `TOPOLO_AGENT_TASK_ID`       | Optional stable host task identifier                      |
 | `TOPOLO_AGENT_NAME`          | Human-readable agent label for audit logs             |
 | `TOPOLO_SERVICE_URL_<ID>`    | Override a service base URL (e.g. `_AUTH`, `_MAIL`)   |
 
-Exactly one credential var must be set. If both are present, `TOPOLO_API_KEY`
-wins.
+An installation ID cannot be combined with a human context, API key, or access
+token. The MCP rejects ambiguous configuration instead of choosing one.
 
 For concurrent organization or environment operation, run one named MCP server
 per stored context. `TOPOLO_CONTEXT` accepts an exact key from `topolo context
@@ -83,11 +98,12 @@ credentials already carry their own immutable context.
 
 ## Startup sequence
 
-1. Resolve an injected credential, a pinned stored context, or the environment's
-   active stored credential. **Refuse to start** if none is available.
+1. Resolve a protected installation, injected credential, pinned stored
+   context, or the environment's active stored credential. **Refuse to start**
+   if none is available. Installation mode exchanges a short-lived Auth token
+   bound to the MCP task, organization, and local DPoP key.
 2. Call `GET /api/me` to load the user's granted scopes + role.
 3. Connect the stdio transport and begin serving MCP requests.
-
 4. Advertise a fixed, bounded discovery/invocation surface. Agents search one
    application at a time and call exact action IDs; the server never expands
    one MCP tool per action or materializes the global catalog.
@@ -100,8 +116,10 @@ clients surface that as a failed server launch.
 
 TopoloMCP is a transport adapter and does not persist customer data. It has no
 database, KV, R2, Durable Object, filesystem-write, analytics, or log-storage
-binding. Credentials remain in the caller-owned environment or the shared CLI
-credential store, and every request is authorized by the target Topolo service.
+binding. Credentials remain in the caller-owned environment, shared CLI
+credential store, or operating-system protected installation store.
+Installation secrets and private keys are never copied into MCP host
+configuration. Every request is authorized by the target Topolo service.
 
 Only messages raised by TopoloMCP's own input validators are returned verbatim.
 Authentication, SDK, provider, session-construction, and unexpected runtime

package/dist/index.js

@@ -3,13 +3,13 @@
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-// node_modules/.pnpm/@topolo+sdk@0.17.1/node_modules/@topolo/sdk/dist/index.js
+// node_modules/.pnpm/@topolo+sdk@0.21.0/node_modules/@topolo/sdk/dist/index.js
 function applyAuthHeaders(headers, credential) {
   if (credential.kind === "api_key") {
     headers.set("X-Api-Key", credential.apiKey);
     return;
   }
-  headers.set("Authorization", `Bearer ${credential.accessToken}`);
+  headers.set("Authorization", `${credential.kind === "dpop_access_token" ? "DPoP" : "Bearer"} ${credential.accessToken}`);
 }
 function applyAuditHeaders(headers, agent, requestId) {
   headers.set("X-Topolo-Client", `${agent.clientName}/${agent.clientVersion}`);
@@ -22,6 +22,54 @@ function generateRequestId() {
   }
   return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 }
+var encoder = new TextEncoder();
+function encodeBase64Url(value) {
+  const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function encodeJson(value) {
+  return encodeBase64Url(encoder.encode(JSON.stringify(value)));
+}
+async function sha256Base64Url(value) {
+  return encodeBase64Url(await crypto.subtle.digest("SHA-256", encoder.encode(value)));
+}
+function publicJwk(privateJwk) {
+  const { crv, kty, x, y } = privateJwk;
+  if (kty !== "EC" || crv !== "P-256" || !x || !y || !privateJwk.d) {
+    throw new TypeError("A private P-256 JSON Web Key is required for DPoP signing.");
+  }
+  return { crv, kty, x, y };
+}
+function canonicalTargetUrl(value) {
+  const url = new URL(value);
+  return `${url.origin}${url.pathname}`;
+}
+async function createDpopProof(input) {
+  const jwk = publicJwk(input.privateJwk);
+  const key = await crypto.subtle.importKey(
+    "jwk",
+    input.privateJwk,
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["sign"]
+  );
+  const header = encodeJson({ alg: "ES256", typ: "dpop+jwt", jwk });
+  const claims = encodeJson({
+    jti: crypto.randomUUID(),
+    iat: Math.floor(Date.now() / 1e3),
+    htm: input.method.toUpperCase(),
+    htu: canonicalTargetUrl(input.targetUrl),
+    ath: await sha256Base64Url(input.accessToken)
+  });
+  const signature = await crypto.subtle.sign(
+    { name: "ECDSA", hash: "SHA-256" },
+    key,
+    encoder.encode(`${header}.${claims}`)
+  );
+  return `${header}.${claims}.${encodeBase64Url(signature)}`;
+}
 var TopoloSdkError = class extends Error {
   code;
   constructor(code, message) {
@@ -1140,7 +1188,7 @@ var TopoloClient = class _TopoloClient {
   timeoutMs;
   fetchImpl;
   credentialProvider;
-  credentialLoadInFlight = null;
+  credentialLoadsInFlight = /* @__PURE__ */ new Map();
   refreshCredential;
   refreshInFlight = null;
   debug;
@@ -1197,7 +1245,16 @@ var TopoloClient = class _TopoloClient {
         `Mutating ${method} requests require { confirm: true }. This guardrail prevents agents from issuing writes without an explicit human-in-the-loop acknowledgement.`
       );
     }
-    await this.loadCurrentCredential();
+    const actionId = requestActionId(opts.headers);
+    const taskId = opts.actorEnvelope?.delegation?.taskId ?? this.actorContext?.taskId;
+    let requestCredential = await this.loadCurrentCredential({
+      service: normalizeLookupKey(opts.service),
+      method,
+      path: opts.path,
+      ...actionId ? { actionId } : {},
+      ...taskId ? { taskId } : {},
+      ...opts.resource ? { resource: opts.resource } : {}
+    });
     const resolvedService = opts.baseUrl ? { serviceKey: normalizeLookupKey(opts.service), baseUrl: this.validatedServiceOrigin(opts.service, opts.baseUrl) } : await this.resolveRequestService(opts.service);
     const baseUrl = resolvedService.baseUrl;
     const url = new URL(opts.path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
@@ -1220,7 +1277,6 @@ var TopoloClient = class _TopoloClient {
     if (opts.body !== void 0) headers.set("Content-Type", "application/json");
     const platformAppId = resolveConfiguredAppId(resolvedService.serviceKey, this.appIds);
     if (platformAppId) headers.set("X-App-ID", platformAppId);
-    applyAuthHeaders(headers, this.credential);
     const actorEnvelope = opts.actorEnvelope === void 0 ? void 0 : parseActorEnvelope(opts.actorEnvelope);
     const requestId = actorEnvelope?.action.requestId ?? generateRequestId();
     applyAuditHeaders(headers, this.agent, requestId);
@@ -1254,9 +1310,19 @@ var TopoloClient = class _TopoloClient {
       }, this.timeoutMs);
       const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
       try {
+        const requestHeaders = new Headers(headers);
+        applyAuthHeaders(requestHeaders, requestCredential);
+        if (requestCredential.kind === "dpop_access_token") {
+          requestHeaders.set("DPoP", await createDpopProof({
+            accessToken: requestCredential.accessToken,
+            method,
+            targetUrl: urlStr,
+            privateJwk: requestCredential.privateJwk
+          }));
+        }
         return await this.fetchImpl(urlStr, {
           method,
-          headers: new Headers(headers),
+          headers: requestHeaders,
           body: opts.rawBody ?? (opts.body !== void 0 ? JSON.stringify(opts.body) : null),
           signal
         });
@@ -1287,13 +1353,13 @@ var TopoloClient = class _TopoloClient {
     };
     let res;
     try {
-      const attemptedCredential = this.credential;
+      const attemptedCredential = requestCredential;
       res = await fetchWithReadRetry();
       if (res.status === 401 && attemptedCredential.kind === "access_token" && this.refreshCredential) {
         await res.body?.cancel().catch(() => void 0);
         const refreshed = await this.refreshRejectedAccessToken(attemptedCredential.accessToken);
         if (refreshed) {
-          applyAuthHeaders(headers, refreshed);
+          requestCredential = refreshed;
           res = await fetchWithReadRetry();
         }
       }
@@ -1383,18 +1449,23 @@ var TopoloClient = class _TopoloClient {
     });
     return parsed;
   }
-  async loadCurrentCredential() {
-    if (!this.credentialProvider) return;
-    this.credentialLoadInFlight ??= this.credentialProvider().then((credential) => {
-      if (!credential) {
-        throw new TopoloAuthError("The configured Topolo credential is no longer available.");
-      }
-      this.credential = credential;
-      return credential;
-    }).finally(() => {
-      this.credentialLoadInFlight = null;
-    });
-    await this.credentialLoadInFlight;
+  async loadCurrentCredential(context) {
+    if (!this.credentialProvider) return this.credential;
+    const key = JSON.stringify(context);
+    let load = this.credentialLoadsInFlight.get(key);
+    if (!load) {
+      load = this.credentialProvider(context).then((credential) => {
+        if (!credential) {
+          throw new TopoloAuthError("The configured Topolo credential is no longer available.");
+        }
+        this.credential = credential;
+        return credential;
+      }).finally(() => {
+        this.credentialLoadsInFlight.delete(key);
+      });
+      this.credentialLoadsInFlight.set(key, load);
+    }
+    return load;
   }
   async refreshRejectedAccessToken(attemptedAccessToken) {
     if (this.credential.kind === "access_token" && this.credential.accessToken !== attemptedAccessToken) {
@@ -1724,6 +1795,14 @@ var TopoloClient = class _TopoloClient {
     const entry = await this.getAction(action);
     return this.executeResolvedAction(entry, input, options);
   }
+  async issueExternalAgentCredential(input) {
+    const actionId = "app_topolo_auth.principal_credentials.issue";
+    const entry = await this.getAction(actionId);
+    if (entry.actionId !== actionId) {
+      throw new TopoloSdkError("unexpected_action", "External agent credential issuance resolved an unexpected action.");
+    }
+    return this.executeResolvedAction(entry, input, { confirm: true }, true);
+  }
   async uploadAction(action, content, input, options) {
     const entry = await this.getAction(action);
     const contract = parseTopoloActionUploadContract(entry.agentContract?.upload);
@@ -1855,7 +1934,7 @@ var TopoloClient = class _TopoloClient {
     }
     return this.executeResolvedAction(entry, input, options);
   }
-  async executeResolvedAction(entry, input, options) {
+  async executeResolvedAction(entry, input, options, preserveSensitiveResult = false) {
     const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
     if (agentAccess === "off") {
       throw new TopoloPermissionError(
@@ -1913,7 +1992,7 @@ var TopoloClient = class _TopoloClient {
       },
       confirm: options.confirm === true || entry.readOnly && !entry.destructive && !entry.requiresConfirmation
     });
-    return redactActionResult(result);
+    return preserveSensitiveResult ? result : redactActionResult(result);
   }
   async buildVerifiedAgentActorEnvelope(actionId, input, resource) {
     if (!this.actorContext) return void 0;
@@ -2389,6 +2468,12 @@ function pickString(value) {
   }
   return void 0;
 }
+function requestActionId(headers) {
+  const value = Object.entries(headers ?? {}).find(
+    ([name]) => name.toLowerCase() === TOPOLO_ACTION_ID_HEADER.toLowerCase()
+  )?.[1];
+  return value?.trim() || void 0;
+}
 function extractRequired(body) {
   if (body && typeof body === "object") {
     const maybe = body;
@@ -3169,10 +3254,15 @@ function createTopolo(options) {
   };
 }
 
-// node_modules/.pnpm/@topolo+sdk@0.17.1/node_modules/@topolo/sdk/dist/node/credential-store.js
-import { mkdir, readFile, writeFile, chmod, rm, stat } from "fs/promises";
+// node_modules/.pnpm/@topolo+sdk@0.21.0/node_modules/@topolo/sdk/dist/node/credential-store.js
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2, chmod as chmod2, rm as rm2, stat } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { homedir as homedir2, platform } from "os";
+import { dirname as dirname2, join as join2 } from "path";
+import { spawnSync } from "child_process";
+import { mkdir, readFile, readdir, rename, rm, writeFile, chmod } from "fs/promises";
 import { existsSync } from "fs";
-import { homedir, platform } from "os";
+import { homedir, platform as hostPlatform } from "os";
 import { dirname, join } from "path";
 var TopoloSdkError2 = class extends Error {
   code;
@@ -3580,18 +3670,150 @@ function topoloServiceOrigins2(serviceUrls, environment) {
     ])
   );
 }
+var KEYCHAIN_SERVICE = "topolo-external-agent-installation";
+function installationStorePath() {
+  const override = process.env.TOPOLO_INSTALLATIONS_PATH?.trim();
+  if (override) return override;
+  const base = process.env.XDG_CONFIG_HOME || (hostPlatform() === "win32" ? join(homedir(), "AppData", "Roaming") : join(homedir(), ".config"));
+  return join(base, "topolo", "installations");
+}
+function installationPath(environment, id) {
+  if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new TypeError("Installation id contains unsupported characters.");
+  return join(installationStorePath(), environment, `${id}.json`);
+}
+function accountName(environment, id) {
+  return `${environment}:${id}`;
+}
+function runOrThrow(result, operation) {
+  if (result.status !== 0) {
+    throw new Error(`${operation} failed: ${(result.stderr || result.error?.message || "platform credential store unavailable").trim()}`);
+  }
+  return result.stdout.trim();
+}
+function createPlatformInstallationSecretBackend(options = {}) {
+  const platform2 = options.platform ?? hostPlatform();
+  const spawn = options.spawn ?? ((command, args, spawnOptions) => spawnSync(command, args, spawnOptions));
+  const root = options.root ?? installationStorePath();
+  if (platform2 === "darwin") {
+    return {
+      async set(account, value) {
+        runOrThrow(spawn("security", [
+          "add-generic-password",
+          "-U",
+          "-a",
+          account,
+          "-s",
+          KEYCHAIN_SERVICE,
+          "-w"
+        ], { input: `${value}
+`, encoding: "utf8" }), "macOS Keychain write");
+      },
+      async get(account) {
+        const result = spawn("security", [
+          "find-generic-password",
+          "-a",
+          account,
+          "-s",
+          KEYCHAIN_SERVICE,
+          "-w"
+        ], { encoding: "utf8" });
+        if (result.status === 44) return null;
+        return runOrThrow(result, "macOS Keychain read");
+      },
+      async delete(account) {
+        const result = spawn("security", [
+          "delete-generic-password",
+          "-a",
+          account,
+          "-s",
+          KEYCHAIN_SERVICE
+        ], { encoding: "utf8" });
+        if (result.status !== 44) runOrThrow(result, "macOS Keychain delete");
+      }
+    };
+  }
+  if (platform2 === "linux") {
+    return {
+      async set(account, value) {
+        runOrThrow(spawn("secret-tool", [
+          "store",
+          "--label=Topolo external agent installation",
+          "service",
+          KEYCHAIN_SERVICE,
+          "account",
+          account
+        ], { input: value, encoding: "utf8" }), "Linux Secret Service write");
+      },
+      async get(account) {
+        const result = spawn("secret-tool", [
+          "lookup",
+          "service",
+          KEYCHAIN_SERVICE,
+          "account",
+          account
+        ], { encoding: "utf8" });
+        if (result.status === 1) return null;
+        return runOrThrow(result, "Linux Secret Service read");
+      },
+      async delete(account) {
+        const result = spawn("secret-tool", [
+          "clear",
+          "service",
+          KEYCHAIN_SERVICE,
+          "account",
+          account
+        ], { encoding: "utf8" });
+        if (result.status !== 1) runOrThrow(result, "Linux Secret Service delete");
+      }
+    };
+  }
+  if (platform2 === "win32") {
+    const secretPath = (account) => join(root, ".secrets", `${account.replace(":", "-")}.bin`);
+    const powershell = (script, path, input) => spawn(
+      "powershell.exe",
+      ["-NoProfile", "-NonInteractive", "-Command", script],
+      { input, encoding: "utf8", env: { ...process.env, TOPOLO_SECRET_PATH: path } }
+    );
+    return {
+      async set(account, value) {
+        const path = secretPath(account);
+        await mkdir(dirname(path), { recursive: true });
+        const script = "$p=$env:TOPOLO_SECRET_PATH;$v=[Console]::In.ReadToEnd();$b=[Text.Encoding]::UTF8.GetBytes($v);$e=[Security.Cryptography.ProtectedData]::Protect($b,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser);[IO.File]::WriteAllBytes($p,$e)";
+        runOrThrow(powershell(script, path, value), "Windows DPAPI write");
+      },
+      async get(account) {
+        const path = secretPath(account);
+        if (!existsSync(path)) return null;
+        const script = "$p=$env:TOPOLO_SECRET_PATH;$b=[IO.File]::ReadAllBytes($p);$d=[Security.Cryptography.ProtectedData]::Unprotect($b,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser);[Console]::Out.Write([Text.Encoding]::UTF8.GetString($d))";
+        return runOrThrow(powershell(script, path), "Windows DPAPI read");
+      },
+      async delete(account) {
+        await rm(secretPath(account), { force: true });
+      }
+    };
+  }
+  throw new Error(`Secure external-agent installation storage is unsupported on ${platform2}.`);
+}
+async function readExternalAgentInstallation(environment, id, backend = createPlatformInstallationSecretBackend()) {
+  const path = installationPath(environment, id);
+  if (!existsSync(path)) return null;
+  const installation = JSON.parse(await readFile(path, "utf8"));
+  const encodedSecret = await backend.get(accountName(environment, id));
+  if (!encodedSecret) throw new Error(`Protected secret is missing for installation ${id}.`);
+  return { installation, secret: JSON.parse(encodedSecret) };
+}
 var ENVIRONMENT_DEFAULT_SERVICE_URLS = TOPOLO_ENVIRONMENT_SERVICE_URLS;
 function configPath() {
   const override = process.env.TOPOLO_CONFIG_PATH;
   if (override) return override;
-  const base = process.env.XDG_CONFIG_HOME || (platform() === "win32" ? join(homedir(), "AppData", "Roaming") : join(homedir(), ".config"));
-  return join(base, "topolo", "config.json");
+  const base = process.env.XDG_CONFIG_HOME || (platform() === "win32" ? join2(homedir2(), "AppData", "Roaming") : join2(homedir2(), ".config"));
+  return join2(base, "topolo", "config.json");
 }
 async function readConfig() {
   const path = configPath();
-  if (!existsSync(path)) return {};
+  if (!existsSync2(path)) return {};
   try {
-    const raw = await readFile(path, "utf8");
+    const raw = await readFile2(path, "utf8");
     return JSON.parse(raw);
   } catch {
     return {};
@@ -3599,11 +3821,11 @@ async function readConfig() {
 }
 async function writeConfig(config) {
   const path = configPath();
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, JSON.stringify(config, null, 2) + "\n", "utf8");
+  await mkdir2(dirname2(path), { recursive: true });
+  await writeFile2(path, JSON.stringify(config, null, 2) + "\n", "utf8");
   if (platform() !== "win32") {
     try {
-      await chmod(path, 384);
+      await chmod2(path, 384);
     } catch {
     }
   }
@@ -3674,18 +3896,18 @@ var CONFIG_LOCK_TIMEOUT_MS = 5e3;
 var CONFIG_LOCK_STALE_MS = 12e4;
 async function withConfigWriteLock(operation) {
   const lockPath = `${configPath()}.lock`;
-  await mkdir(dirname(lockPath), { recursive: true });
+  await mkdir2(dirname2(lockPath), { recursive: true });
   const startedAt = Date.now();
   while (true) {
     try {
-      await mkdir(lockPath);
+      await mkdir2(lockPath);
       break;
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
       try {
         const lock = await stat(lockPath);
         if (Date.now() - lock.mtimeMs > CONFIG_LOCK_STALE_MS) {
-          await rm(lockPath, { recursive: true, force: true });
+          await rm2(lockPath, { recursive: true, force: true });
           continue;
         }
       } catch (inspectionError) {
@@ -3701,7 +3923,7 @@ async function withConfigWriteLock(operation) {
   try {
     return await operation();
   } finally {
-    await rm(lockPath, { recursive: true, force: true });
+    await rm2(lockPath, { recursive: true, force: true });
   }
 }
 async function refreshCredentialIfNeeded(environment = selectedEnvironment(), options = {}) {
@@ -4539,14 +4761,14 @@ function displayAppId(entry) {
 
 // src/version.ts
 import { readFileSync } from "fs";
-import { dirname as dirname2, join as join2 } from "path";
+import { dirname as dirname3, join as join3 } from "path";
 import { fileURLToPath } from "url";
 function readMcpVersion() {
   try {
-    const here = dirname2(fileURLToPath(import.meta.url));
+    const here = dirname3(fileURLToPath(import.meta.url));
     const candidates = [
-      join2(here, "package.json"),
-      join2(here, "..", "package.json")
+      join3(here, "package.json"),
+      join3(here, "..", "package.json")
     ];
     for (const path of candidates) {
       try {
@@ -4668,6 +4890,9 @@ function toolError(context, error) {
   };
 }
 
+// src/context-credential.ts
+import { randomUUID } from "crypto";
+
 // src/auth.ts
 function resolveCredentialFromEnv(environment = "production") {
   const prefix = environment === "production" ? "TOPOLO_PRODUCTION" : `TOPOLO_${environment.toUpperCase()}`;
@@ -4678,12 +4903,102 @@ function resolveCredentialFromEnv(environment = "production") {
   return null;
 }
 
+// src/installation-credential.ts
+function audienceFor(context) {
+  const actionAudience = context.actionId?.match(/^(app_[A-Za-z0-9_]+)\./)?.[1];
+  if (actionAudience) return actionAudience;
+  if (context.actionId) {
+    throw new TopoloMcpPublicError("The requested Topolo action has an invalid audience.");
+  }
+  const service = context.service.trim().toLowerCase();
+  if (/^app_[a-z0-9_]+$/.test(service)) return service;
+  if (!/^[a-z0-9_-]+$/.test(service)) {
+    throw new TopoloMcpPublicError("The requested Topolo service cannot be bound to this installation.");
+  }
+  return `app_topolo_${service.replace(/-/g, "_")}`;
+}
+function responseData(value) {
+  if (!value || typeof value !== "object") return {};
+  const record2 = value;
+  return record2.data && typeof record2.data === "object" ? record2.data : record2;
+}
+async function resolveExternalAgentInstallationCredential(environment, installationId, taskId, options = {}) {
+  const stored = await (options.readInstallation ?? readExternalAgentInstallation)(environment, installationId);
+  if (!stored) throw new TopoloMcpPublicError(`Installation ${installationId} is not registered on this device.`);
+  if (stored.installation.id !== installationId || stored.installation.environment !== environment) {
+    throw new TopoloMcpPublicError(`Installation ${installationId} is not registered for ${environment}.`);
+  }
+  if (!stored.installation.clientId.trim() || !stored.installation.organizationId.trim() || !/^[A-Za-z0-9_-]{43}$/.test(stored.installation.dpopJkt) || !stored.secret.clientSecret.trim() || !stored.secret.privateJwk.d) {
+    throw new TopoloMcpPublicError(`Installation ${installationId} is incomplete or corrupted.`);
+  }
+  const fetchImpl = options.fetch ?? fetch;
+  const now = options.now ?? Date.now;
+  const authBaseUrl = resolveServiceUrl("auth", options.serviceUrls);
+  const tokenUrl = new URL("/api/developer-oauth/token", authBaseUrl).toString();
+  const cache = /* @__PURE__ */ new Map();
+  const credentialProvider = async (context) => {
+    const audience = audienceFor(context);
+    const resource = context.resource ?? {
+      resourceType: "organization",
+      resourceId: stored.installation.organizationId
+    };
+    const boundTaskId = context.taskId?.trim() || taskId;
+    const key = JSON.stringify({ audience, taskId: boundTaskId, resource });
+    const cached = cache.get(key);
+    if (cached && cached.expiresAt - 15e3 > now()) return cached.credential;
+    const body = new URLSearchParams({
+      grant_type: "client_credentials",
+      client_id: stored.installation.clientId,
+      client_secret: stored.secret.clientSecret,
+      audience,
+      task_id: boundTaskId,
+      resource_type: resource.resourceType,
+      resource_id: resource.resourceId,
+      dpop_jkt: stored.installation.dpopJkt
+    });
+    const response = await fetchImpl(tokenUrl, {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: body.toString()
+    });
+    const payload = await response.json().catch(() => null);
+    const data = responseData(payload);
+    const accessToken = typeof data.access_token === "string" ? data.access_token : "";
+    const expiresIn = Number(data.expires_in);
+    if (!response.ok || !accessToken || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+      throw new TopoloMcpPublicError("The external-agent installation credential was rejected.");
+    }
+    const credential2 = {
+      kind: "dpop_access_token",
+      accessToken,
+      privateJwk: stored.secret.privateJwk
+    };
+    cache.set(key, { credential: credential2, expiresAt: now() + expiresIn * 1e3 });
+    return credential2;
+  };
+  const credential = await credentialProvider({
+    service: "auth",
+    method: "GET",
+    path: "/api/auth/me",
+    taskId,
+    resource: {
+      resourceType: "organization",
+      resourceId: stored.installation.organizationId
+    }
+  });
+  return { credential, credentialProvider, installation: stored.installation, taskId };
+}
+
 // src/context-credential.ts
 var DEFAULT_DEPENDENCIES = {
   readConfig,
   refreshContextCredentialIfNeeded,
   refreshCredentialIfNeeded,
-  resolveCredentialFromEnv
+  resolveCredentialFromEnv,
+  resolveInstallationCredential: resolveExternalAgentInstallationCredential
 };
 function resolvePinnedContextKey(profile, selector) {
   const normalized = selector.trim().toLowerCase();
@@ -4704,9 +5019,35 @@ function resolvePinnedContextKey(profile, selector) {
   }
   throw new TopoloMcpPublicError(`TOPOLO_CONTEXT "${selector}" is not signed in for this environment`);
 }
-async function resolveMcpCredential(environment, selector = process.env.TOPOLO_CONTEXT, dependencies = DEFAULT_DEPENDENCIES) {
+async function resolveMcpCredential(environment, selector = process.env.TOPOLO_CONTEXT, dependencies = DEFAULT_DEPENDENCIES, installationSelector = process.env.TOPOLO_AGENT_INSTALLATION_ID, taskSelector = process.env.TOPOLO_AGENT_TASK_ID) {
   const environmentCredential = dependencies.resolveCredentialFromEnv(environment);
   const requestedSelector = selector?.trim();
+  const installationId = installationSelector?.trim();
+  if (installationId) {
+    if (requestedSelector || environmentCredential) {
+      throw new TopoloMcpPublicError(
+        "TOPOLO_AGENT_INSTALLATION_ID cannot be combined with TOPOLO_CONTEXT or an environment credential"
+      );
+    }
+    const taskId = taskSelector?.trim() || `task_${randomUUID()}`;
+    const config2 = await dependencies.readConfig();
+    const serviceUrls = resolveServiceUrls(
+      profileForEnvironment(config2, environment).serviceUrls,
+      environment
+    );
+    const resolved = await dependencies.resolveInstallationCredential(
+      environment,
+      installationId,
+      taskId,
+      { serviceUrls }
+    );
+    return {
+      credential: resolved.credential,
+      contextKey: null,
+      credentialProvider: resolved.credentialProvider,
+      taskId: resolved.taskId
+    };
+  }
   if (environmentCredential) {
     if (requestedSelector) {
       throw new TopoloMcpPublicError("TOPOLO_CONTEXT cannot be combined with an environment credential");
@@ -4809,7 +5150,10 @@ async function runStdioMcp(dependencies = DEFAULT_DEPENDENCIES2) {
   const topolo = dependencies.createTopolo({
     credential,
     environment,
-    actorContext: { channel: "mcp" },
+    actorContext: {
+      channel: "mcp",
+      ...resolvedCredential.taskId ? { taskId: resolvedCredential.taskId } : {}
+    },
     agent: {
       clientName: "topolo-mcp",
       clientVersion: MCP_VERSION,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@topolo/mcp",
   "packageManager": "pnpm@10.17.1",
-  "version": "0.12.0",
-  "topoloPublishedVersion": "0.12.0",
+  "version": "0.13.0",
+  "topoloPublishedVersion": "0.13.0",
   "description": "Model Context Protocol server for the Topolo platform. Exposes scope-gated tools that third-party agents (Claude, Codex, etc.) can call natively.",
   "license": "UNLICENSED",
   "author": "Topolo",
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@topolo/sdk": "0.17.1"
+    "@topolo/sdk": "0.21.0"
   },
   "devDependencies": {
     "@types/node": "^20.12.0",