`get_accessible_tenants`

Updated May 19, 20261 min read

List tenants accessible to the current user. Returns each tenant's id, name, allowed merchants, and subscription summary.

This is the canonical first call in any MCP session. The server-published agent guidance requires it: agents must validate any user-requested tenant against this list before invoking shipment or report tools.

Parameters

None — the tool takes no input. The tenant list is derived from the authorized user's JWT.

Returns

An array of tenant records. Each entry includes:

tenantId — the id you'll pass to every other MCP tool.
tenantName — display name.
allowedMerchants — merchants within the tenant the user can act on.
subscriptionSummary — high-level subscription / entitlement info.

Example agent prompt

"Which Carriyo environments can I access?"

get_accessible_tenants()

The agent narrates the result: "You have access to two tenants — Acme Production and Acme Staging. Which one would you like to work with?"

Common chain

The standard agent first turn:

get_accessible_tenants
       │
       ▼
get_merchants(tenantId="…")
       │
       ▼
…the user's actual question, scoped…

get_merchants — merchants the user can use within a chosen tenant.
All other MCP tools require tenantId. Resolve it here.

Notes

The result is small and cheap to fetch. Don't try to skip this for performance reasons — agent clients typically cache the result for the session.
If the result is empty, the user has no tenant access — the agent should stop and surface that, not try to call shipment tools.

get_accessible_tenants