@topolo/mcp 0.11.12 → 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