Start from published contracts
Agents use public documentation and the credential-scoped application and action catalog to learn how to operate Topolo. They should discover identifiers, inspect the selected action, retrieve its guide, and follow its verification and recovery. A source checkout is not needed for customer operations.
npm install --global @topolo/cli
topolo auth login
topolo setup
topolo doctor
topolo whoami --json
Keep each agent's context stable
topolo context ls --json
Choose the exact key returned for the intended context. Set TOPOLO_CONTEXT on that process rather than switching one shared active context. A named MCP registration can pin the same context with topolo setup --name <connection-name> --context <returned-context-key>; verify it with topolo doctor --name <connection-name>. Replace these placeholders before running them. An injected API key carries its own immutable context and must not be combined with TOPOLO_CONTEXT.
OAuth scopes define what the token may request. Application grants, action permissions, resource bindings and target runtime policy determine effective access. Discovery is not authorization. Treat a runtime 403 as authoritative.
Discover resources and action instructions
topolo apps --json
topolo actions --service topolo-docs --limit 100 --json
topolo actions get app_topolo_docs.public_machine.index --detail --json
topolo actions examples app_topolo_docs.public_machine.index --json
For a selected application, use topolo resources <application> --json for resource identifiers and topolo workspaces list <application> --json for workspace lifecycle policy. Do not substitute an organization identifier for an application workspace. Pass any required resource type and identifier separately from the action input.
Follow the action's published guide and machine URL when present. Private guide retrieval must use the published authorized retrieval instructions. Public machine indexes expose only explicitly published documents. Retain the retrieved version identifier and content hash when citing instructions.
| Operation | MCP tool |
|---|---|
| Check identity | topolo_whoami |
| Find an application | topolo_search_applications, topolo_get_application |
| Discover resources | topolo_get_resource_types, topolo_list_resources |
| Check workspace policy | topolo_list_workspaces |
| Find actions | topolo_search_actions, topolo_discover_capabilities |
| Read a contract and examples | topolo_get_action, topolo_get_action_examples |
| Validate and plan | topolo_prepare_action or topolo_validate_action, topolo_plan_action |
| Execute an automatic read | topolo_read_action |
| Execute an authorized mutation | topolo_call_action with confirm: true |
Plan, authorize, execute and verify
Validate the exact input against the published schema. Review an executable plan before a call. Planning does not execute the action. For mutations, show the exact action and resolved request, input and resource context, effects, verification and recovery. Obtain authorization unless the concrete work is already authorized; transport confirmation alone is not user approval.
Keep the approved input unchanged during execution. Afterward, perform every published verification step and compare the returned identifiers and state. When a response is uncertain, read the current state before retrying; a network error does not prove that a mutation had no effect. Use only the action's published recovery, with authorization for any compensating mutation.
Handle returned credentials safely
Local CLI and stdio MCP can replace action credentials with opaque topolo-secret: references in the OS protected store. Pass the reference unchanged to the next published action; never extract its underlying value. References are bound to the verified identity, context and environment, and expire after 30 minutes.
After the workflow finishes, release a reference with topolo actions release-secret <reference> --confirm --json or topolo_release_action_secret with confirm: true. This removes the local reference; it does not revoke the upstream credential. Use the published revocation action separately when required.
Stop on missing or denied contracts
Branch on structured error codes and preserve request identifiers. Correct schema errors without inventing fields. Reauthenticate for an authentication failure. Do not bypass a permission denial. If documentation lacks the concrete input, response, effect, verification or recovery needed for safe execution, report the missing contract for that action.
Use topolo api only when public documentation publishes a complete exact API contract. A missing action does not authorize a guessed private endpoint.