Use @topolo/mcp to give an MCP-capable host typed tools for Topolo discovery and authorized actions. Version 0.14.27 depends on SDK 0.23.22. It belongs to the CLI 0.13.12 dependency cohort described here, dated 15 October 2026; these instructions describe the exact released cohort. [M1, M2]
Register the compatible server
The normal customer installation is the CLI, which owns the exact compatible MCP and SDK. On a workstation approved for this version, the illustrative setup sequence is:
npm install -g @topolo/cli@0.13.12
topolo setup
topolo doctor
setup configures the supported host with the resolved local Node entry from the installed dependency graph. doctor performs authentication and MCP checks. Existing managed installations and credential profiles need their owner's upgrade and startup authority before these operations. Do not replace a managed installation merely to reproduce this guide. Advanced hosts can use the exported @topolo/mcp/stdio entry; normal customer setup avoids a network-dependent npx launcher. [M1, M4]
Select one credential context
Choose one supported credential mode: a protected agent installation, an injected API key or access token, a pinned stored context, or the active stored credential. An installation ID cannot be combined with a human context or injected credential. TOPOLO_CONTEXT pins a stored context; do not combine it with an injected key or token, whose context is already fixed. No organization override belongs in a tool call. [M1]
For concurrent contexts, discover exact context keys through the CLI and create named registrations. These examples are illustrative; replace the context placeholder with a returned key:
topolo context ls --json
topolo setup --name topolo-example --context '<discovered context key>' --env production
topolo doctor --name topolo-example
The named server reads and refreshes its selected stored credential without changing the CLI's shared active context. Keep installation secrets and private keys in the protected credential store, outside host configuration. Production is the default customer environment; another environment requires its supported configuration and authorization. [M1, M4]
Discover a task through the tools
Start with identity, then narrow discovery to one application. The following sequence names the published tools rather than inventing an app-specific action ID:
topolo_whoamiidentifies the credential's principal, organization, and permissions.topolo_search_applicationsandtopolo_get_applicationresolve an accessible application.topolo_get_resource_types,topolo_list_resources, andtopolo_list_workspacesresolve the task's resource boundary.topolo_search_actionsandtopolo_discover_capabilitiesnarrow the task inside that application.topolo_get_actionandtopolo_get_action_examplesprovide the exact contract and example prerequisites.
Read the discovered schemas, permissions, effects, verification instructions, and recovery behavior before preparing input. Use full contract detail when needed. Discovery is credential-scoped and paginated; a page is not a global application inventory. Runtime-authorized actions still require the target service to accept the concrete caller, input, and resource. [M1]
Prepare and execute the same request
Use topolo_validate_action and topolo_plan_action, or topolo_prepare_action for combined preparation. Resolve missing identifiers instead of executing an example that requires discovery. Supply optional resource context as the paired resourceType and resourceId; it selects a workspace or another published resource alias without changing the credential's organization. [M1]
Use topolo_read_action for a published automatic read. Use topolo_call_action for an authorized mutation with explicit confirmation. The host confirmation and confirm: true do not replace the user's task authorization or the target application's permission decision. Workspace creation, renaming, default selection, uploads, and agent invocations can have effects. topolo_list_workspaces exposes the caller-specific policy.canCreate and policy.reason; organization ownership alone is insufficient. [M1]
After an action, follow its verification contract and check the actual record, version, or job outcome. Use topolo_api_call only when the published documentation provides the exact endpoint contract and ordinary action discovery does not cover the task. A mutation through this escape hatch still needs confirmation and service authorization.
Continue an agent invocation
topolo_run_agent uses a stable idempotency key and returns an invocation result. In this exact release, its adapter maps an underlying awaiting_approval status to the returned state approval_required, with a verificationUrl and continuation instructions. Show that URL and continue the same invocation, with the same input, resource context, and idempotency key. The returned continuation adds waitForApproval: true and waitSeconds: 120. Do not start a second invocation to continue approval. [M3]
A running or approval state is not completion. Report the terminal result and preserve a terminal failure or cancellation. This state mapping is specific to 0.14.27 and should not be substituted with an unverified convention from a different MCP release.
Pass protected results without revealing them
Local stdio workflows use opaque topolo-secret:<id> references for protected action credentials. Pass the reference unchanged to the next approved action. References are bound to the verified identity and environment and expire after 30 minutes. Do not transfer them to another host or extract their contents. When its workflow is finished, the published topolo_release_action_secret tool with confirmation deletes the local reference; it does not revoke an upstream credential. HTTP or Worker hosts remain redacted unless configured with a protected SDK store. [M1, M3]
Understand the transport and dependency boundaries
MCP 0.14.27 pins Topolo SDK 0.23.22. Its transport-independent dist/dispatch.js, dispatch declarations, HTTP declarations, and README match the previous 0.14.26 bytes; the shipped stdio and HTTP JavaScript bundles and package manifest changed. The unchanged tool definitions do not imply an unchanged credential runtime. [M1, M2, M3]
The package declares a compatible @modelcontextprotocol/sdk range. The CLI 0.13.12 cohort separately pins protocol SDK 1.31.0; keep that resolved cohort distinct from the broad range in the MCP manifest. A dependency update or an installed directory does not establish that an already running host has reloaded it. [M2, M4]
For hosted integrations, the public @topolo/mcp/http export provides createTopoloMcpHttpHandler. Its options include the mount path, effective environment, service URL overrides, app-ID overrides, agent label and fetch implementation. The default mount is /mcp; the default environment is production. The handler constructs a client from the validated environment and the request's credential. [M5]
This example is illustrative and unexecuted:
import { createTopoloMcpHttpHandler } from '@topolo/mcp/http';
const handler = createTopoloMcpHttpHandler({ path: '/mcp' });
export default { fetch: handler.fetch };
A hosted handler and a local stdio server have different credential and lifecycle boundaries. Local protected action references are not portable bearer tokens. Do not infer HTTP OAuth issuer migration, host permission, or native task completion from this transport example or from a protocol dependency version. [M1, M5]
Account for saved sign-in recovery
SDK 0.23.22 can mark a terminal saved grant for shared device reauthorization, and distinguishes retryable rate limits from terminal grant refusal. A stdio startup can therefore reach authentication work while resolving its saved credential. The MCP adapter does not promise an interactive awaitReauthorization UI or a particular raw SDK error shape to every host: startup failures are sanitized by its own public-error boundary. Resolve the approved sign-in through the credential owner and then separately qualify host restart and task results. Do not print raw saved-profile data or retry a held profile because a backoff interval elapsed. [M6]
Diagnose a failed setup or request
If the server cannot resolve an unambiguous credential or rejects startup authentication, resolve the approved host configuration with its owner. Do not place a reusable secret in a host settings file or switch identities to overcome a refusal.
A missing tool may reflect credential visibility. A discovered action may still be denied by current target policy. Preserve the sanitized error and request ID, verify the selected application and resource, and follow the published recovery contract. Do not infer broad access from startup introspection, automatically widen a key, or replay a mutation with an unknown outcome. MCP transport setup, a successful identity read, and native agent task completion are separate results. [M1]
Sources for this version
[M1] Published MCP 0.14.27 archive, member package/README.md.
[M2] The same archive, member package/package.json. The exact SDK dependency is 0.23.22 despite an older SDK label in retained README prose.
[M3] The same archive, members package/dist/dispatch.js and package/dist/dispatch.d.ts.
[M4] Published CLI 0.13.12 archive, members package/package.json and package/skills/topolo/SKILL.md.
[M5] The MCP archive, members package/dist/http.d.ts and package/dist/http.js.
[M6] The MCP archive, member package/dist/index.js, and SDK 0.23.22 archive, member package/dist/node/credential-store.js. Setup commands and handler code are illustrative and unexecuted.